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.

Base URL

All API requests to Device Magic must be made to the following URL (note the HTTPS):

https://www.devicemagic.com/organizations/[organization_id]/

where your organization_id is evident from the URL to your dashboard when browsing www.devicemagic.com/organizations/[organization_id]/.

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)

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://www.devicemagic.com/clients/[device_identifier]/oneshots
HTTP POST https://www.devicemagic.com/clients/Android_35175104564712/oneshots

The device_id 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://www.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>
  <comments>Easy, wasn't it?</comments>
</oneshot>

The <dm:form_description> 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 (be careful, as this could confuse users), use the dm:form_name tag.

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:

<oneshot_list>
  <oneshot>
    <id>60</id>
    <namespace>http://www.devicemagic.com/xforms/demo/b4bcf250-2fcb-012f-f75c-0026b0eb68e4?52aa3980-5592-012f-33e8-0026b0eb68e4</namespace>
    <name>Oneshot Test</name>
  </oneshot>
</oneshot_list>

JSON Example 

HTTP 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."
    }
}

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",
    "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 pushed 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 oneshot you want to update at the end.

HTTP PUT https://www.devicemagic.com/clients/[device_identifier]/oneshots/[oneshot_id]
HTTP PUT https://www.devicemagic.com/clients/Android_35175104564712/oneshots/53

The device_id url parameter is obtained from the Devices API.

The oneshot_id is available within the information that is returned when you created the oneshot or by checking outstanding PUSH Forms (below)

For the body of your PUT, the JSON looks like this:

{
    "payload" : {
        "comments" : "Something new!"
    }
}

You can also change the form name and description too:

{
    "form_name" : "I have renamed my dispatch!",
    "form_description" : "Cause description",
    "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 /clients/[device_identifier]/oneshots

You can also query for outstanding oneshots across all devices for your organization:

GET /organizations/[organization_id]/oneshots

XML Example
You will receive an XML document containing each form’s details:

<?xml version="1.01" encoding="UTF-8"?>
<forms type="array">
  <form>
    <description>This is a sample Push Form</description>
    <device-id type="integer">4837</device-id>
    <id type="integer">40007</id>
    <name>A First Form</name>
    <namespace>http://www.devicemagic.com/xforms/demo/2d3698c0-650c-012e-7e8e-12313b079c72?b10e3ba0-6521-012e-197f-12313b079c72</namespace>
    <organization-id type="integer">3569</organization-id>
    <parent-form-id type="integer">
      4995510
    </parent-form-id>
    <parent-form-version>
      1.00
    </parent-form-version>
  </form>
</forms>

JSON Example

[{
    "form": {
        "id": 4837,
"name": "A First Form",
"namespace": "http://www.devicemagic.com/xforms/demo/2d3698c0-650c-012e-7e8e-12313b079c72?b10e3ba0-6521-012e-197f-12313b079c72",
"version": "1.01",
"organization_id": 3569,
"device_id": 4837,
"description": "This is a sample Push Form",
"parent_form_id": 4995510,
"parent_form_version": "1.00"
    }
}]

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).

Revoking Dispatched Forms

To revoke a form, issue an HTTP DELETE as follows:

DELETE /clients/[device_identifier]/oneshots/[oneshot_id]

where the [oneshot_id] is obtained by performing an enquiry as above.

To revoke all oneshots for a particular device, use:

POST /clients/[device_identifier]/oneshots/destroy_all

Advanced Usage

Replacing Resources In Dispatches

Pushing Images & GPS Co-ordinates

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.

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.

Did this answer your question?