OpenMRS-jr

Owned by Michael Downey
Last updated: Mar 16, 2014Version comment
13 min read

Introduction

OpenMRS-jr (pronounced OpenMRS junior) is a mobile application developed using the JavaRosa platform. In the latest version the user can:

  • Specify a base URL for a working OpenMRS installation
  • Login to the app with a valid OpenMRS username and password
  • Download the list of available cohorts of patients
  • Select a cohort of patients to download, and download the patients onto the mobile device
  • Download XForms onto the mobile device from OpenMRS
  • Select a patient, and fill out one or more XForms for that patient
  • Fill out a form for a patient not currently on the phone using their patient identifier
  • Register new patients

The application uses the Xforms module and is built on top of JavaRosa. The application hasn't been tested extensive on different phones but in theory it should work on most J2ME compatible phones.

Prerequisites

Working OpenMRS installation with XForms Module installed

  • Install OpenMRS
  • Install the XForms Module
  • Configure xform module
    • Login to your OpenMRS installation and select "Administration" from the menu bar
    • Select Manage Global Properties from the Maintenance section.
      • Scroll down to xforms.showModelXmlTab and type "true" in place of the "false".
      • Locate xforms.showXformsSourceTab and type "true" in place of the "false".
      • Locate xforms.xformSerializer and set it to "org.openmrs.module.xforms.serialization.DefaultXformSerializer".
      • Create a new property called xforms.xsltJR and paste the following XSLT stylesheet as it's value: 
        <?xml version='1.0' encoding='UTF-8'?>
<xsl:stylesheet version='2.0'
xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
xmlns:fn='http://www.w3.org/2005/xpath-functions'
xmlns:xf='http://www.w3.org/2002/xforms' >
<xsl:output method='xml' version='1.0' encoding='UTF-8'/>
<xsl:template match='/'>
 <html xmlns='http://www.w3.org/1999/xhtml'
       xmlns:xf='http://www.w3.org/2002/xforms'
       xmlns:xsd='http://www.w3.org/2001/XMLSchema'
       xmlns:xs='http://www.w3.org/2001/XMLSchema'
       xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
       xmlns:ev='http://www.w3.org/2001/xml-events'
       xmlns:jr='http://openrosa.org/javarosa'
 >
<head>   
     <title>
        <xsl:value-of select='/xf:xforms/xf:model/xf:instance/*/@name'/>
    </title>
   
    <xf:model>
         <xsl:copy-of select='/xf:xforms/xf:model/xf:instance' />

        <xsl:for-each select='/xf:xforms/xf:model/xf:bind'>
       
             <xsl:copy>
                <xsl:attribute name='id'>
                     <xsl:value-of select='@id' />
                 </xsl:attribute>
                
                <xsl:attribute name='nodeset'>
                     <xsl:value-of select='@nodeset' />
                 </xsl:attribute>
                
                 <xsl:if test='string-length(normalize-space(@type)) > 0'>
                    <xsl:attribute name='type'>
                         <xsl:value-of select='@type' />
                     </xsl:attribute>
                 </xsl:if>
                
                 <xsl:if test='string-length(normalize-space(@visible)) > 0'>
                     <xsl:attribute name='visible'>
                         <xsl:value-of select='@visible' />
                     </xsl:attribute>
                 </xsl:if>
                
                 <xsl:if test='string-length(normalize-space(@readonly)) > 0'>
                     <xsl:attribute name='readonly'>
                         <xsl:value-of select='@readonly' />
                     </xsl:attribute>
                 </xsl:if>
                
                 <xsl:if test='string-length(normalize-space(@required)) > 0'>
                     <xsl:attribute name='required'>
                         <xsl:value-of select='@required' />
                     </xsl:attribute>
                 </xsl:if>
                
                 <xsl:if test='string-length(normalize-space(@locked)) > 0'>
                     <xsl:attribute name='readonly'>
                         <xsl:value-of select='@locked' />
                     </xsl:attribute>
                 </xsl:if>
                
                 <xsl:if test='string-length(normalize-space(@calculate)) > 0'>
                     <xsl:attribute name='calculate'>
                         <xsl:value-of select='@calculate' />
                     </xsl:attribute>
                 </xsl:if>
                
                 <xsl:if test='string-length(normalize-space(@relevant)) > 0'>
                     <xsl:attribute name='relevant'>
                         <xsl:value-of select='@relevant' />
                     </xsl:attribute>
                 </xsl:if>
       
                <xsl:if test='string-length(normalize-space(@constraint)) > 0'>
                    <xsl:attribute name='constraint'>
                         <xsl:value-of select='@constraint' />
                     </xsl:attribute>
                </xsl:if>
       
                <xsl:if test='string-length(normalize-space(@message)) > 0'>
                    <xsl:attribute name='jr:ConstraintMSG'>
                         <xsl:value-of select='@message' />
                     </xsl:attribute>
                </xsl:if>
               
                <xsl:if test="@id='patient.medical_record_number'">
                                         <xsl:attribute name="jr:preload">
                                           <xsl:text>context</xsl:text>
                                         </xsl:attribute>

                                         <xsl:attribute name="jr:preloadParams">
                                             <xsl:text>preloaded-patient-identifier</xsl:text>
                                         </xsl:attribute>
                                </xsl:if>

   
           </xsl:copy>
        
        </xsl:for-each>

       </xf:model>
      
 </head>
 
 <body>
     <xsl:for-each select='/xf:xforms/*'>
       <xsl:if test='local-name() != "model"'>
             <xsl:copy-of select='.' />
       </xsl:if>
     </xsl:for-each>
 </body>
 </html>
 
</xsl:template>
</xsl:stylesheet>
        If copying and pasting doesn't work try copying and pasting from this text file. (Note: this is an updated format which will allow you to enter forms based on the patient identifier rather them already being synchronized to the phone.)

Creating A Compatible XForm

The simplest form acceptable consists of three sections: Patient information, Encounter information and Observation information. The following fields MUST be present: PATIENT.PATIENT_ID, ENCOUNTER.ENCOUNTER_DATETIME, ENCOUNTER.LOCATION_ID and ENCOUNTER.PROVIDER_ID.  If entering patients by patient identifier you must also include PATIENT.PATIENT_MEDICAL_RECORD_NUMBER.

Designing the XForm

The simplest method of creating a form is to go Administration in your OpenMRS instance and select "Manage Forms"

  • Duplicate the Basic Form
  • Scroll down to "Schema design" and delete all extra fields so that it looks like this:
  • Then Save the form.
  • Click on "Design XForm"
  • Click on PATIENT ID on the left Form Fields.
  • Uncheck Enabled and Required on the properties tab.
  • Then go to File and click Save (this must be done to ensure the XFORM is created from the form).
  • Once saved, your XForm should be downloaded to the phone with the "Download Forms" option in the Form List on the device.

Use Cases

The functionality supported by OpenMRS-JR allows the user to download a list of patients as well as a list of forms and fill out a form for a patient and then either submit it back to the server or save it for later submission. A JavaRosa specific form allows users of OpenMRS-JR to submit patient registration information to an OpenMRS server, thus allowing patients to be created. These functions can be broken down into these two use cases.

Download Forms and Cohorts, and Fill out a form for a patient

  • Download a list of patients based on an existing OpenMRS cohort.
  • Select a patient from the cohort on the mobile or to enter the patient identifier of a patient that is not already on the phone.
  • Download forms from OpenMRS or select one that was previously downloaded and stored on the phone.
  • Fill out the selected form.
  • Submit back to the xforms module and have it appear in OpenMRS like any other encounter.

Creating new OpenMRS Patients

  • Load JR
  • Create a new patient registration
  • Submit Registration to Server

Installing the mobile application

The application can be installed on your mobile phone by visiting this link in your phone's browser: 
https://wiki.openmrs.org/download/attachments/4489666/OpenMRS-JR.jad

If your phone gives problems downloading the application via the JAD, access the JAR directly at:
https://wiki.openmrs.org/download/attachments/4489666/OpenMRS-JR.jar

Get the initial OpenMRS-JR release at:
http://bitbucket.org/cell_life/openmrs-jr/downloads/OpenMRS-JR.jad

Developer Guide

OpenMRS-JR requires a JavaROSA build. JavaROSA is hosted at bitbucket.org and can be downloaded using the instructions on their wiki: http://bitbucket.org/javarosa/javarosa/wiki/Home It is highly recommended that the Demo project in JavaROSA be compiling and running as a precursor to OpenMRS-JR.

OpenMRS-JR is also hosted at bitbucket.org and the process of checking out the source is exactly the same as that of JavaROSA:

The bitbucket repository is: http://bitbucket.org/cell_life/openmrs-jr

Once the Eclipse project has been checked out and imported into Eclipse, locate the build.properties and local.properties files and update the following parameters as required:

  • wtk.home=<path-to-sun-wireless-tool-kit-folder>
  • polish.home=<path-to-polish-home-(uses-Polish-2.1)>
  • dir.root=<root-of-openmrs-jr-folder>

Development/testing of OpenMRS-jr was done with the following server configuration...

  • Server: Last Build: Mar 10 2010 03:59 PM  Version: 1.6.0 dev Build 11699 (Also confirmed working with Version: 1.6.0 Build 12644 and Version: 1.7.0 RC Build 15604)
  • Form Import Export 1.6.0
  • HTML Form Entry 1.6.1
  • XForms 3.8.8 (Also confirmed working with 3.9.2)
  • Reporting Compatibility 1.5.0.2

Video demos

A video showing the application at work can be seen here: http://screenr.com/WEA

An updated version showing entry based on the patient identifier can be seen here: http://www.youtube.com/watch?feature=player_detailpage&v=nheEOnKZYzQ

Feature List

Properties

  • Enter the base URL for the OpenMRS server.  This should include the http://, and a the server port, and implementation directory, such as http://192.168.4.7:8080/openmrs
  • All other URLs are generated off this base URL. If this URL is incorrect, none of the form download, patient download, cohort download, patient creation, user authentication, or form submission features will work.

Login

  • Enter the username and password.
  • If the user has not logged in using the phone before, authenticate the user by contacting the server and saving the user profile.
    • otherwise simply verify the password using the local user profile.

Cohorts

Shows a list of cohorts. Selecting a cohort causes the list of patients to be downloaded. Once the patients are downloaded, proceed to Patient List screen.  Note: you must have a saved cohort (a saved patient search is not adequate).  If you don't have a saved cohort, you cannot proceed to the forms.

Patient Select

This is the central screen of the app. It shows a list of patients. If there are no patients, load the Cohorts screen and download a list of available cohorts from the server. From this screen, it is possible to download more patients (via the cohort screen), view and download forms, create new OpenMRS patients, or view any unsent forms. Selecting a patient moves focus to the Patient Details screen, and then to the Form List screen.

Patient Details

This screen shows the patients= basic demographic details.

Downloading Forms

Show a list of forms already on the phone, and presents the option to download more forms or update the existing forms with newer versions of the forms. Newly downloaded forms overwrite existing forms with the same name. Selecting a form opens the form for filling.

Filling a Form

This screen navigates the user through each question in the form prompting the user for answers. The user can move forwards or backwards through questions, or exit the form.

Saving A Form For Later Sending

When the compulsory questions in a form are filled out, the form becomes able to be saved. Saved forms can be sent at a later stage either individually or as a group of forms.

Viewing Unsent Forms

When the compulsory questions in a form are filled out, the form becomes able to be saved. Saved forms can be sent at a later stage either individually or as a group of forms.

Creating A New Patient

It is possible to create OpenMRS patients. When this feature is selected, a form loads and the user is prompted to fill data for the minimum fields that OpenMRS requires for a patient creation. Once the form is filled out, and the form submitted, the newly created patient should be visible in the patient list in OpenMRS. Note that for the phone to download the new patient, there has to be a cohort that includes this patient, and the user needs to re-download that cohort.

Feedback from Initial Testing (using Nokia N80 and MFU W71)

  • Failure to enter a valid base URL (for example omitting the port number), or if the server is unreachable causes  an "Unhandled exception. Close application?" error, if the user has not logged in previously.
  • The login is insecure.  The username and password are passed through a URL post to OpenMRS. On some phones, it shows the URL including the password in plain text when the user verifies that they want to connect to the server.  The username and password are also included in the PostURL in the program settings for anyone to see.
  • An "Exit" option should be added to each major section of the program, or some means of navigating to the main screen so you can exit properly.
  • If a bad password is entered, it stores it in the PostURL setting, and you are unable to send forms.
  • MAJOR: Was unable to send forms because the patient_id didn't exist in OpenMRS.  The form should accept the patient identifier, not the internal OpenMRS patient_id.  If the patient_id doesn't exist, it should be sent to a default patient, and/or the user should be notified there is a problem with the ID.

xForms 3.9.3 and later

  • When attempting to access http://192.168.4.14:8080/openmrs/module/xforms/patientDownload.form?downloadCohorts=true&serializerKey=xforms.cohortSerializer&uname=admin&pw=test it gives an error "Privileges required: [projects:View Patient Cohorts]".  This makes it incompatible with the current version of OpenMRS-jr.  This is a change for the better in the long-run, as the username and password in the URL was a security flaw in 3.8.8.
  • Forms appear in OpenMRS-jr when downloaded even if they are not marked as published in OpenMRS. - I originally had this as an OpenMRS-jr error, but I believe the xForms module should handle this.  First it should check on the user privileges and if the user doesn't have the "View Unpublished Forms" privilege, it should not include the unpublished forms in the form list.  It should never include forms that are retired in the xformslist when downloaded to mobile devices.

Feedback from Latest Testing (using Nokia C3-00) and November 22, 2011 version of OpenMRS-JR.jad and OpenMRS-JR.jar.

Note: This version includes new features.  1.) Ability to fill out a form for a patient not currently on the phone. 2.) Ability to use it with the Nokia C3 QWERTY keypad equipped phone.

The test server configuration is OpenMRS Version: 1.8.2 Build 21762, XForms Module version 4.0.5, and Reporting Compatibility 1.5.3.

The following is a list of corrections that remain to be made to this version of OpenMRS-JR.

Bug/Task Number

Priority

Description

1

Low

When logging into OpenMRS-JR for the first time, you must hit the backspace key (or various other keys) before the field will allow you to type in the server address.

2

Medium

When entering the password, you must hit an initial button before it will take you to the field to actually fill in the password.  This could be confusing because you may think you have entered the first character of your password, but it didn't actually accept it.

3

Medium

When selecting the "Login" button it give a menu where you must choose Login a second time, or Exit.

4

Medium

When entering the "OpenMRS Patient Identifier" you must hit a button before it will allow you to enter the actual patient identifier.

5

Low

When selecting the form to fill out, it gives the popup menu of other options.  It should go straight to the form that was highlighted.

6

Medium

When filling out the form, you must press Select, Select (or various other keys) to enter the encounter datetime. It should go straight to the field to start accepting the date.

7

High

After entering the "OpenMRS Patient Identifier", pressing Select causes a popup menu to appear.  No menu should be shown and it should proceed to "Goto forms" directly.

8

Enhancement

Require double-entry of the "OpenMRS Patient Identifier" to ensure it's entered properly. Refuse the entry if they don't match.

9

High

When filling out the form, when you press the select button, it causes a pop-up menu to appear.  There should be no menu to confirm the selection. Note: it doesn't matter which field type, it should never show this menu.

10

High

When choosing to send the form now or send the form later, don't show the popup menu (with the only option to Select the field). Do the selected action immediately.

11

High

After sending forms or trying to send forms and they fail to send; either "sending now" after filling out the form or when sending all forms later, the program freezes, or gets stuck, or gets stuck in a loop to send the forms again.

12

Enhancement

Optionally limit the "OpenMRS Patient Identifier" field to numeric values only.

13

Highest Priority - Enhancement

After OpenMRS-JR is initially installed, and the field has a value stored, do no show the URL screen for future logins.

14

Low

After sending forms, it gives a message 

"Successfully Submitted. Today we have received ${0} forms from you."

  The value for number of forms never changes.  Either have it tell you how many forms have been received, or remove the last phrase of the message.

15

 

Multi-Select observations in the form cause the program to crash...
"ko ko unhandled exception in gui-clp => java.lang.NullPointerException[null]" (To create a Multi-Select field, in the form Schema, check the box next to "Select Multi?", and then design the form.

16

Low

Passwords longer than 10 characters are not accepted.

17

High

At the username and password login screen, selecting Login without entering a password allows the user to enter the program.

18

Low

Remove 'SMS Test (Munaf)' from the hard-coded list of forms.

19

Low

When downloading forms to the telephone after the initial form download, it adds a duplicate form name to the list of forms.  If the form is already on the telephone, it should simply replace the currently existing form with the new form that was just downloaded.

20

Low

If you choose to "Send Current" from the list of completed forms under "View Unsent" (when none are selected) it causes an error...
Index Out of Bounds java/lang/IndexOutOfBoundsException the index [-1] is not valid for this list with the size [0].

21

High

When there are many forms that have been entered and stored on the phone to send later, and you connect to the network, "View Unsent", and choose to "Send all", not all of the forms are sent.

22

CRITICAL

Error in server log when attempting to upload forms from phone: ERROR - XformsQueueProcessor.submitXForm(297) |2012-03-14 12:32:06,017| Expected patient family name value java.lang.Exception: Expected patient family name value.  Click to see the full stack trace. This may be the root cause of bug 21 above. This doesn't happen for all patients that the forms are filled out for.  All are being entered by the Identifier rather than being chosen from the list on the phone. - This error happened because the patient identifier the user entered didn't exist.  See XFRM-65.

23

Low

If you choose to "Send Current" or "Send All" from the list of completed forms under "View Unsent", it should not prompt the user if they want to "Send now" or "Send later".  It should connect and send immediately.

24

Low (for now)

The cohorts of patient demographics are not cached on the phone.  If you are working offline, the list of patients isn't visible without connecting to the server.

25

High

There was a change to the XForms module that prevents OpenMRS-jr from connecting to XForms 4.0.9.7 and later.  4.0.9.5 works properly.  See Daniel for info on the change he made.

26

Low

Patient XForm Design (for creating a new patient) doesn't sync to phone.