Clone wiki

javarosa / HistoricalFormDownloadAPI


The functionality we are after can loosely be described as a way to download data that can be inserted into a form. This data would be downloaded as instances that are specific to a particular device or user. This design explicitly pushes more functionality to the server. Our experience suggests that we should make the phone should be as naive as possible.


Someone using ODK Collect wants to fill out a encounter forms for all patients in the catchment area who have been lost to follow up. The list of patients are assigned in OpenMRS and the hospital already has some data (demographics, previous encounter, labs, etc) about each patient.

The user logs into the phone and sends OpenMRS's XForms module a user specific identifier. The server matches the identifier to the list of patients assigned to this user and generates the set of instances. Each instance has varying amounts of data, but all have a xlmns attribute that ties it to a form. The server also generates a simple and short string that will be used by ODK Collect as the name of the instance. In this case, it is the "Patient Name (Patient Id)".

In ODK Collect, the user views (and maybe searches) the list of instances and downloads them to the device. If the form is for that instance is not available, there should be the option to download those as well. From there, they can select the instance they wish to complete and it will launch the appropriate form filling activity. In the case of ODK Collect, this will just like completing a saved form.

Once finished, the completed form can be sent back to OpenMRS. Because the server tracks which instances are sent to which devices, it will be able to track the state of each instance over time.


We've been thinking that the server does not validate the data that it puts in instance -- the form on the phone will validate everything before it returns data. Is this prudent? It seems at the minimum, we can do some intelligent things to make sure the data types are correct...

The set of instances should be structured in the same way the form download is structured. Assuming something like a manifest, there will likely be externally readable metadata (md5, date-generated, etc) included for each instance. Internal metadata (as specified by the OpenRosa spec) will be available once an instance is downloaded. The manifest will also likely include pointers to the form they belong to. This framework can also ensure the phone has all the necessary forms and instances.

The string for the name of the instance is designed to be human readable and searchable. This complexity of this string is a contentious issue. For example, should you also include say gender and date of birth so the user can filter on that information? If you do, do you have to send templating information to the device to ensure proper display?