...
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".
- 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:
...
Code Block
...
<?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>
...
If
...
- copying
...
- and
...
- pasting
...
- doesn't
...
- work
...
- try
...
- copying
...
- and
...
- pasting
...
- from
...
- this
...
- text
...
- file
...
- from
...
- the
...
- cell-life
...
- dev
...
- server.
...
...
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.
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: 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
...
.
...
These
...
links
...
are
...
for
...
the
...
initial
...
version.
...
(Links
...
for
...
the
...
latest
...
version
...
are
...
currently
...
at
...
the bottom of this page.)
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
...
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
...
demo
...
A
...
video
...
showing
...
the
...
application
...
at
...
work
...
can
...
be
...
seen
...
here
...
:
...
...
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
...
...
- 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.
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:
- Then Save the form.
- Click on "Design XForm"
- 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)
- 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
|
...
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. |
There are move bugs to be written up, but this is the initial start.