Learn about Moca Dispatch Server

From MoCa Development Wiki

The MDS provides a JSON API (http://json.org). Here is how to interact with it:

These are the currently active URL-mappings from the base URL of the MDS:
json/patient/list
json/patient/(?P<id>[0-9-]+)
json/validate/credentials
json/procedure/submit
json/binarychunk/submit
json/textchunk/submit

The standard response message from the MDS is a JSON object with the following properties:
- status : a status code that is either 'SUCCESS' or 'FAILURE'
- data : a free form field that can be used to pass structure data back, or to return a message. In the case of failure, this is usually a human-readable string describing why.

json/patient/list
- username : OpenMRS username
- password : OpenMRS password

Returns a list of all patients in the 'data' field formatted like so: firstYYYYMMDDlastID
Patient records are joined with a '##' separator.

json/patient/(?P<id>[0-9-]+)
- username : OpenMRS username
- password : OpenMRS password

Returns an individual record formatted like in json/patient/list. The id to lookup is encoded in the URL mapping.

json/validate/credentials
- username : OpenMRS username
- password : OpenMRS password

If the credentials succeed, returns a success message, otherwise a failure message. The data element is a human readable message about the login result.

json/procedure/submit
- username : OpenMRS username
- password : OpenMRS password
- savedproc_guid : A unique identifier for this instance of the procedure.
- procedure_guid : A unique identifier for the procedure executed.
- responses : see format description below
- phone : a unique identifier for the reporting phone, usually its telephone number

This is the procedure text submission interface. When you have filled out a Moca procedure and are ready to upload it to the Moca Queue, then a Moca client would submit to this URL. On success or failure, a diagnostic message is provided in the 'data' field.

The responses item is a JSON dictionary. The keys of this dictionary are the unique procedure element ID's of each response in responses. The value of each element in the dictionary is a dictionary of information about the response. This dictionary has the following properties:

- id : the id of the element
- type : indicates the type of the element
- answer : the answer to the question

In the case of a binary type, the answer section is a comma separated list of unique ids that will be used to refer to each binary uploaded for this question. (see the binary submission interface below)

json/binarychunk/submit
json/textchunk/submit
- procedure_guid : the saved procedure that this binary chunk is a part of
- element_id : the element is to which this binary chunk applies
- element_type : the type of the element
- binary_guid : a unique identifier for this binary
- file_size : the total size of the binary
- byte_start : the starting byte this chunk applies to
- byte_end : the end byte this chunk applies to
- byte_data : the data of the binary chunk itself

Moca files are uploaded in dynamically sized chunks, and each chunk is uploaded via this interface. In the case of the binarychunk handler, the byte_data is a POSTed file, while in the textchunk handler, byte_data is the byte data, Base 64 encoded. textchunk is a workaround for networks that actively block HTTP file uploads. The handlers respond with success or failure messages to indicate whether they were successful. The MDS is the ultimate arbiter of how much of a given binary is uploaded, so a properly implemented client must verify that a chunk's result is a success before moving onto the next.