Page Comparison

Introduction

Wiki Markup
h2. Introduction OpenMRS-jr (pronounced OpenMRS junior) is a mobile application developed using the JavaRosa platform. In this 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

...


* 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".

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 are 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.
Be able to select a patient on the mobile and fill out a downloaded form.
Be able to download an existing form, or load a form from memory.
Submit back to the xforms module and have it appear in OpenMRS as if you entered it using infopath.

Image Removed

Creating new OpenMRS Patients

Load JR
Create a new patient registration
Submit Registration to Server

Image Removed

Installing the mobile application

...




h2. Prerequisites


h3. Working OpenMRS installation with XForms Module installed

* [Install OpenMRS|docs:Installing OpenMRS]
* [Install the XForms Module|docs: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".
*** Create a new property called _xforms.xsltJR_ and paste the following XSLT stylesheet as it's value:
{code}
<?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.patient_id'">
                                         <xsl:attribute name="jr:preload">
                                           <xsl:text>context</xsl:text>
                                         </xsl:attribute>

                                         <xsl:attribute name="jr:preloadParams">
                                             <xsl:text>preloaded-patient-id</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>
{/code}


h2. 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 are can be broken down  into these two use cases.


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

* Download a list of patients based on an existing OpenMRS cohort.
* Be able to select a patient on the mobile and fill out a downloaded form.
* Be able to download an existing form, or load a form from memory.
* Submit back to the xforms module and have it appear in OpenMRS as if you entered it using infopath.

!Mobilemrs-uc3.png|border=1!


h3. Creating new OpenMRS Patients

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

!Mobilemrs-uc2.png|border=1!


h2. Installing the mobile application

The application can be installed on your mobile phone by visiting this link in your phone's browser: [http://bitbucket.org/cell_life/openmrs-jr/downloads/OpenMRS-JR.jad|http://bitbucket.org/cell_life/openmrs-jr/downloads/OpenMRS-JR.jad] If your phone gives problems downloading the application via the JAD, access the JAR

...

 directly at: [http://bitbucket.org/cell_life/openmrs-jr/downloads/OpenMRS-JR.jar|http://bitbucket.org/cell_life/openmrs-jr/downloads/OpenMRS-JR.jar

...

Developer Guide

]













h2. 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|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|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:

]













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&nbsp; Version: 1.6.0 dev Build 11699

...


* Form Import Export 1.6.0

...


* HTML Form Entry 1.6.1

...


* XForms 3.8.8

...


* Reporting Compatibility 1.5.0.2

...



h2. Video demo

...



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

...

Feature List

Properties

...

|http://screenr.com/WEA]
















h2. Feature List


h3. Properties

* Enter the base URL for the OpenMRS server.&nbsp; 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

...

Image Removed

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.

Image Removed

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.

Image Removed

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.

Image Removed

Patient Details

This screen shows the patients= basic demographic details.

Image Removed

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.

Image Removed

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.

Image Removed

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.

Image Removed

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.

Image Removed

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.

Image Removed

Creating A Compatible XForm

The simplest form acceptable consists of 3 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.

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:

Image Removed

Then Save the form.
Click on "Design XForm"

Image Removed

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 on the "Download Forms" option in the Form List on the device.

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

...

.

!OJRProperties.jpg|border=1!



h3. 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.

!OJRLogin.jpg|border=1!


h3. 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.&nbsp; Note: you must have a saved cohort (a saved patient search is not adequate).&nbsp; If you don't have a saved cohort, you cannot proceed to the forms.


!OJRCohorts.jpg|border=1!



h3. 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.

!OJRPatientselect.jpg|border=1!



h3. Patient Details

This screen shows the patients= basic demographic details.


!OJRPatientdetail.jpg|border=1!



h3. 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.


!OJRChooseForm.jpg|border=1!



h3. 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.


!OJRFormfilling.jpg|border=1!



h3. 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.


!OJRSendingForms.jpg|border=1!



h3. 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.


!OJRUnsentForms.jpg|border=1!



h3. 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.


!OJRNewPatient.jpg|border=1!


h2. Creating A Compatible XForm

The simplest form acceptable consists of 3 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.


h3. 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:

!SchemaDesign.png|border=1!

* Then Save the form.
* Click on "Design XForm"

!XForms_Designer.png|border=1!

* 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 on the "Download Forms" option in the Form List on the device.

h3. 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&nbsp; an "Unhandled exception. Close application?" error, if the user has not logged in previously.
* The login is insecure.&nbsp; 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.&nbsp; 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.
* Xforms doesn't show additional selections for providers or locations when they are added after the form is created.&nbsp; This is an XForms 3.8.8 bug, as they didn't show up in the web interface until recreating the xform either.
* Forms appear in OpenMRS-jr when downloaded even if they are not marked as published in OpenMRS.
* Xforms are downloaded from the server, but they don't show up properly  on the list of forms.&nbsp; (they download and appear properly with the dev.cell-life.org server, so there is probably a server configuration step missing in the instructions) This happens on both test phones. They only  appear as a cursor above the or below the two forms that are hard coded  into the program. "jr-patient-single-reg" and "SMS Test (Munaf)"

...


* 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.

...

&nbsp; The form should accept the patient identifier, not the internal OpenMRS patient_id.

...

&nbsp; 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.

Versions Compared

Old Version 15

New Version 16

Key

Introduction

Prerequisites

Working OpenMRS installation with XForms Module installed

Use Cases

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

Creating new OpenMRS Patients

Installing the mobile application

Developer Guide

Feature List

Properties

Cohorts

Patient Select

Patient Details

Downloading Forms

Filling a Form

Saving A Form For Later Sending

Viewing Unsent Forms

Creating A New Patient

Creating A Compatible XForm

Designing the XForm

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