External Applications

HTTP Connection URL s

When interfacing with external applications like mobile clients, the following urls are used for various functions:

• Uploading Multiple Data Forms: http://server:8080/openmrs/moduleServlet/xforms/xformDataUpload?batchEntry=true&uname=name&pw=password
•  
• Uploading One Data Form as a multipart request: http://server:8080/openmrs/moduleServlet/xforms/xformDataUpload?uname=name&pw=password

• Uploading One Data Form with request body as xml: http://server:8080/openmrs/module/xforms/xformDataUpload.form?uname=name&pw=password

• Downloading Form List: http://server:8080/openmrs/moduleServlet/xforms/xformDownload?target=xformslist&uname=name&pw=password
  For JavaRosa clients, add this parameter: "&format=withurl", such that it becomes: http://server:8080/openmrs/moduleServlet/xforms/xformDownload?target=xformslist&uname=name&pw=password&format=withurl

• Downloading Forms: http://server:8080/openmrs/moduleServlet/xforms/xformDownload?target=xforms&uname=name&pw=password

• Downloading One Form: http://server:8080/openmrs/moduleServlet/xforms/xformDownload?target=xform&uname=name&pw=password&formId=id&contentType=xml&excludeLayout=true

You can also optionally add another parameter with name "xsltKey" which should have a value of the OpenMRS global property having an xslt document to transform the xform to your custom format. For example, if you are using a JavaRosa based client, you could add something like: xsltKey=xforms.xsltJR where you have an OpenMRS global property, called xforms.xsltJR, having the xslt document.

• Downloading Cohorts: http://server:8080/openmrs/module/xforms/patientDownload.form?downloadCohorts=true&serializerKey=xforms.cohortSerializer&uname=name&pw=password

• Downloading Patients: http://server:8080/openmrs/module/xforms/patientDownload.form?downloadPatients=true&serializerKey=xforms.patientSerializer&uname=name&pw=password

• Downloading Users: http://server:8080/openmrs/moduleServlet/xforms/userDownload?uname=name&pw=password
  where "server, name, password and 8080" are your openmrs server, user name, password and port respectively.

For form data upload, you can as well just dump the forms on the file system in the xforms queue. The queue folder is determined by the global property "xforms.queue_dir". Just ensure that the xforms queue task is scheduled and running.

Bluetooth Connections

When connecting using Bluetooth, you will need to ensure that the "XForms Bluetooth Task" is running, after setting a few properties.
You find this task by selecting "Manage Scheduler" on the Administration screen.
On selecting this task and click "Properties", you can set the following properties:

• ServerUUID: This is a 32 character unique identifier of the Bluetooth service listening for connections. The module puts a default value which is fine as long as you have no other bluetooth service using it. This is the same value you need to specify at the client.
• ServerIP: This is the IP Address or name of the OpenMRS server.
• ServiceName: This is the name you want displayed for this Bluetooth service.

SMS Connections

Settings

When connecting using SMS, you will need to ensure that the "XForms SMS Task" is running, after setting a few properties.
You find this task by selecting "Manage Scheduler" on the Administration screen, then click "Properties".
On selecting this task and click "Properties", you can set the following properties:

• ModemPort: The port at which the modem is connected.
• ModemId: A string to uniquely identify this modem from any other that could be connected to the same server. This property is not critical.
• ModemBaudRate: The baud rate you want for data transfer for this modem.
• ModemSrcPort: The port from which server messages are sent. This property is not critical.
• ModemManufacturer: The manufacturer of the modem. This property is not critical.
• MsgDestPort: The port at which Java Midlets are listening.
• ModemModel: This model of the modem. This property is not critical.
  When a property is not critical, it means that even if you do not change its value from the default, everything will work fine.

Form Filling

Filling of forms using basic text SMS is done by sending an SMS according to the structure as explained below:

• The first word should be an openmrs user name.
• The Second is password
• The Third is formId
• Followed by space separated list of question positions (as in the xform) and answers. The question position and answer are separated by the equal sign "=" character, or any other character as set in the "xforms.smsFieldSepChar" global property.

For instance one can fill the basic form displayed in the xforms designer screen shot XForms Module Form Designer by sending an sms with these contents:
"daniel daniel123 1 2=3 3=1 4=67.5 9=ID001" where "daniel" is the user name, "daniel123" is the password, "1" is the formId, "2" is the position of the location question in the xform, "3" is the third location as per the location list in the xform, "3" is the position of the xform provider question, "1" is the first provider in the xform provider list, "4" is the position of the weight question, "67.5" is the value of weight, "9" is the position of the medical record number question, and "ID001" is the value of the medical record number.
Since medical record number is the patient identifier, a new encounter will be created for patient with identifier "ID001".
If no such patient exists, then a new patient will be created and the encounter added to him or her. For new patient creation, the sex, family name, and birth date questions have to also be filled together with another question for the identifier type.
When processing the xform on the server, all validation in the xform will be applied and any errors sent back as an SMS to the phone sender.

Patient Download

You can download a set of patients in a given cohort by passing the cohort identifier or you can download a set of patient that match a given patient identifier or name.

Forms Download

When you download forms to external applications, the default just downloads only those forms you uploaded into the database by either using the "Upload XForm" link or saving from the xforms designer. For now this is the only way of allowing you to select which forms are to be downloaded on the normally resource constrained devices. But if you want to download all forms as automatically created by the module, then on the Administration screen, select "Manage Global Properties" and set the value of the "xforms.useStoredXform" to "false"

Resources

• XForms Module
• XForms Module User Guide
• XForms Module Patient Registration
• XForms Module Form Designer
• XForms Module Technical Overview
• ?XReports Module ReportDesigner Technical Overview
• ?XForms Module Release Notes
• Download Module
• GitHub project (source code)
• XForms was discussed on a May 9th University call. Watch xforms video
• ?XForms Newbies FAQs