The API is implemented as a RESTful web service, with appropriate GET, PUT, POST & DELETE verbs. To use the API, one needs to obtain an access token and pass this along in each call – please see our authentication article for more information.
Once a form is “pushed” to a device, it lives on the device until it is submitted. In this way, it can be an effective task list for the user. API methods exist to inquire about outstanding forms as well as revoke forms that were previously pushed.
Have a look at the API in action in this article.
Device Enquiry
Before anything useful can be accomplished, a list of devices connected and approved for the organization needs to be obtained. This can be obtained as follows:
HTTP GET /organizations/[organization_id]/devices.(json|xml)
Take a look at this article for more information on our Devices API.
Sending a Dispatch
Pushing a form to an organization’s device will trigger a notification if the app is closed. The app icon’s badge indicator will also reflect the amount of uncompleted pushed forms.
The push API is that it allows a “copy” of an existing form (the “template”) to be sent to a device with some of the field values automatically populated. Programmatically, an XML payload is POST'ed as follows (be sure to set the content type to “application/xml”):
XML Example
HTTP POST https://api.devicemagic.com/api/v2/devices/[device_identifier]/dispatches.xml
HTTP POST https://api.devicemagic.com/api/v2/devices/Android_35175104564712/dispatches.xml
(Deprecated) POST https://api.devicemagic.com/clients/[device_identifier]/oneshots
Note on 'Deprecated' examples: the "oneshots" language has been replaced by “dispatches”. Both terms will work for the time being, but depreciated items will eventually be phased out. No date is currently set for its removal.
The device_identifer url parameter is obtained from the Devices API. In the following XML snippet, we are referencing an existing “template” form via it’s form namespace. The easiest way to get this form in XML format is via the Forms API. See the demo form below, “A First Form”.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<h:html xmlns="http://www.w3.org/2002/xforms" xmlns:dm="http://www.devicemagic.com/XMLSchemaDataTypes" xmlns:ev="http://www.w3.org/2001/xml-events" xmlns:h="http://www.w3.org/1999/xhtml" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<h:head>
<h:title>A First Form</h:title>
<model>
<instance xmlns="http://www.devicemagic.com/xforms/demo/2d3698c0-650c-012e-7e8e-12313b079c72">
<untitled_form_1>
<quality_of_day/>
<inbox_overflow/>
<next_holiday/>
<comments/>
</untitled_form_1>
</instance>
<bind nodeset="inbox_overflow" type="boolean"/>
<bind nodeset="next_holiday" type="date"/>
</model>
</h:head>
<!-- BODY section omitted -->
</h:html>
Notice the xmlns attribute on the instance node? This is that particular form’s namespace.
The form's namespace can be acquired from the xml or json version of your forms index page:
https://api.devicemagic.com/organizations/[organization_id]/forms.(xml|json)
We’re also going to be substituting the “comments” field with some predefined values. So the XML fragment we POST to the endpoint above turns out to be:
<?xml version='1.0'?>
<oneshot xmlns='http://www.w3.org/2002/xforms' xmlns:dm='http://mobileforms.devicemagic.com/xforms' xmlns:h='http://www.w3.org/1999/xhtml' xmlns:xsd='http://www.w3.org/2001/XMLSchema'>
<dm:form_name>This is optional - you can omit this element</dm:form_name>
<dm:form_namespace>http://www.devicemagic.com/xforms/demo/2d3698c0-650c-012e-7e8e-12313b079c72</dm:form_namespace>
<dm:form_description>This is a sample Push Form</dm:form_description>
<dm:location>lat=35.7773663, long=-78.63876549999999</dm:location>
<dm:address>227 Fayetteville St Suite 802, Raleigh, NC 27601, USA</dm:address>
<dm:scheduled_at>2020-02-10T23:04:40+02:00</dm:scheduled_at>
<comments>Easy, wasn't it?</comments>
</oneshot>
The <dm:form_description> (optional) tag allows you to supply some additional text to the UI, the limit is 255 characters.
If you want to replace the entire form name, use the dm:form_name tag.
The <dm:location> (optional) allows you to assign location coordinates to a dispatch.
The <dm:address> (optional) allows you to name a place, this should be used with <dm:location> property's Lat/long.
The <dm:scheduled_at> (optional) should be a timestamp in ISO 8601 format to specify when devices should receive a dispatch.
In the event of a successful POST, you will receive an HTTP 202 Created. The Payload of a successful POST is XML describing the submitted oneshot:
<?xml version="1.0" encoding="UTF-8"?>
<dispatch>
<id type="integer">301</id>
<name>Test dispatch form</name>
<namespace>http://www.devicemagic.com/xforms/demo/2d3698c0-650c-012e-7e8e-12313b079c72</namespace>
<version>1.01</version>
<organization-id type="integer">7</organization-id>
<device-id type="integer">4</device-id>
<description>This is a sample Push Form</description>
<parent-form-id type="integer">198</parent-form-id>
<parent-form-version>1.00</parent-form-version>
<created-at type="dateTime">2020-03-13T13:48:58Z</created-at>
<scheduled-at type="dateTime">2020-03-13T13:48:56Z</scheduled-at>
</dispatch>
JSON Example
HTTP POST https://api.devicemagic.com/api/v2/devices/[device_identifier]/dispatches.json
(Deprecated) POST /clients/[device_identifier]/oneshots
Please don’t forget to set your authentication header, as well as the content type:
Content-Type: application/json
Authorization: Basic KJHG865fytSDadsst6y7u566eA==
For the body of your POST, the JSON looks like this:
{
"form_namespace" : "http://www.devicemagic.com/xforms/e1848a68-08dd-4425-a377-c27059bcaa8f",
"payload" : {
"comments" : "Nothing to see here. Move along."
}
}You can also change the form name and description too:
{
"form_namespace" : "http://www.devicemagic.com/xforms/e1848a68-08dd-4425-a377-c27059bcaa8f",
"form_name" : "My Simple Form",
"form_description" : "Just testing oneshots",
"payload" : {
"comments" : "Nothing to see here. Move along."
}
}Optionally, set a location, address, and schedule the form to be dispatched. For more information, please refer to the XML example above.
{
"form_namespace": "http://www.devicemagic.com/xforms/e1848a68-08dd-4425-a377-c27059bcaa8f",
"location": "lat=35.7773663, long=-78.63876549999999",
"address": "227 Fayetteville St Suite 802, Raleigh, NC 27601, USA",
"scheduled_at": "2020-02-10T23:04:40+02:00",
"payload": {
"comments": "Easy, wasn't it?"
}
}If you have repeat groups and subforms that you’d like to push values for, it’ll need to look like this:
{
"form_namespace": "http://www.devicemagic.com/xforms/e1848a68-08dd-4425-a377-c27059bcaa8f",
"location": "lat=35.7773663, long=-78.63876549999999",
"address": "227 Fayetteville St Suite 802, Raleigh, NC 27601, USA",
"scheduled_at": "2020-02-10T23:04:40+02:00",
"payload" : {
"question_1" : "asparagus",
"subform_1" : {
"inner_question" : "beetroot",
"inner_question_2" : "cabbage"
},
"question_2" : "dates",
"repeat_group_1" : [
{
"repeat_group_question_1" : "elderberries",
"repeat_group_question_2" : "figs"
},
{
"repeat_group_question_1" : "grapes",
"repeat_group_question_2" : "haricots"
}
]
}
}
Updating a Dispatch
Updating an existing dispatched form is very similar to creating it, just the url needs to change and you do not need a form namespace in the payload.
The URL needs the id of the dispatch you want to update at the end.
HTTP PATCH https://api.devicemagic.com/api/v2/devices/[device_identifier]/dispatches/[dispatch_id].(xml|json)
HTTP PATCH https://api.devicemagic.com/api/v2/devices/Android_35175104564712/dispatches/53.json
(Deprecated) PUT https://api.devicemagic.com/clients/[device_identifier]/oneshots/[oneshot_id]
The device_identifier url parameter is obtained from the Devices API.
The dispatch_id is available within the information that is returned when you created the dispatch or by checking outstanding PUSH Forms (below)
For the body of your PATCH, the JSON looks like this:
{
"payload" : {
"comments" : "Something new!"
}
}You can also change the other attributes listed below:
{
"form_namespace": "http://www.devicemagic.com/xforms/a189a8b0-e816-0137-7257-2cde48001122",
"form_name": "This is optional - you can change this element!",
"form_description": "This is a sample Push Form",
"location": "lat=35.7773663, long=-78.63876549999999",
"address": "227 Fayetteville St Suite 802, Raleigh, NC 27601, USA",
"scheduled_at": "2020-02-10T23:04:40+02:00",
"payload": {
"comments": "Something new!"
}
}
Fetching Outstanding Dispatched Forms
In the event you want to inquire which forms are still outstanding for a device, simply issue a GET request as follows:
GET https://api.devicemagic.com/api/v2/devices/[device_identifier]/dispatches.(xml|json)
(Deprecated) GET /clients/[device_identifier]/oneshots
You can also query for outstanding oneshots across all devices for your organization:
GET https://api.devicemagic.com/api/v2/organizations/[organization_id]/dispatches.(xml|json)
(Deprecated) GET /organizations/[organization_id]/oneshots
XML Example
You will receive an XML document containing each form’s details:
<?xml version="1.0" encoding="UTF-8"?>
<dispatches type="array">
<dispatch>
<id type="integer">296</id>
<name>Test Dispatch form</name>
<namespace>http://www.devicemagic.com/xforms/1234-123-123?1234-123-123</namespace>
<version>1.01</version>
<organization-id type="integer">7</organization-id>
<device-id type="integer">4</device-id>
<description>Test Dispatch form description</description>
<parent-form-id type="integer">198</parent-form-id>
<parent-form-version>1.00</parent-form-version>
<created-at type="dateTime">2020-03-13T13:48:58Z</created-at>
<scheduled-at type="dateTime">2020-03-13T13:48:56Z</scheduled-at>
</dispatch>
</dispatches>
JSON Example
{
"dispatches": [
{
"id": 296,
"name": "Test Dispatch form",
"namespace": "http://www.devicemagic.com/xforms/1234-123-123?1234-123-123",
"version": "1.01",
"organization_id": 7,
"device_id": 4,
"description": "Test Dispatch form description",
"parent_form_id": 270,
"parent_form_version": "1.02",
"created_at": "2020-03-12T14:47:22.000Z",
"updated_at": "2020-03-12T14:47:22.000Z",
"scheduled_at": "2020-02-10T21:04:40.000Z",
},
]
}You will notice a new namespace has been generated for this form (it’s simply the original namespace with a question mark and a GUID following).
Retrieve Dispatched Values
If you need to retrieve a dispatch and view the values dispatched to a form, you can do so as follows:
User dispatch:
GET
https://api.devicemagic.com/api/v3/users/[user_identifier]/dispatches/[dispatch_id].(xml|json)?include_inputs=true
Device dispatch:
GET
https://api.devicemagic.com/api/v3/devices/[device_identifier]/dispatches/[dispatch_id].(xml|json)?include_inputs=true
Revoking Dispatched Forms
To revoke a form, issue an HTTP DELETE as follows:
DELETE https://api.devicemagic.com/api/v2/devices/[device_identifier]/dispatches/[dispatch_id].(xml|json)
(Deprecated) DELETE /clients/[device_identifier]/oneshots/[oneshot_id]
dispatch_id is obtained by performing an inquiry as above.
To revoke all oneshots for a particular device, use:
POST https://api.devicemagic.com/api/v2/devices/[device_identifier]/dispatches/destroy_all.(xml|json)
(Deprecated) POST /clients/[device_identifier]/oneshots/destroy_all
Pushing Images & GPS Co-ordinates
Dispatch Images
Binary fields can be populated just as you would a regular field, but you have to Base64 encode the binary image data as a string.
Dispatch Locations
Pushing GPS co-ordinates for a location question enables you to populate a location question. Every location question in the Mobile Forms app has a “Show on Map” from wherein you can invoke the native device navigation app, if available. For example, populate the field as follows:
<customer-address>lat=17.977768, long=-76.782512</customer-address>
Note that the above format is the same as the location format received when forms are submitted, without the accuracy components.
Advanced Usage