Push API

With this API, you can extend the basic Mobile Forms platform in two important ways:

  1. Enable pre-population of form templates with values loaded from a database, for example.

  2. Build complex workflow scenarios where the submission of one form can trigger delivery of another to a manger, for example.

Have a look at the API in action over here:

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 topic for more information. Your API token can be obtained from your “Edit Organization” screen.

Once a form is “pushed” to a device, it lives on the device until the user completes and submits it. In this way, it can be an effective task list for the user. API methods exist to enquire about outstanding forms as well as revoke forms that were previously pushed.

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

The resulting XML fragment will look similar to the following:

<?xml version="1.0" encoding="UTF-8"?>
<devices type="array">
  <device>
    <description nil="true"></description>
    <id type="integer">4836</id>
    <identifier>iPhone_d6e2542effafbcc8d0e6bf0ef2917b76dea4faf8</identifier>
    <organization-id type="integer">3569</organization-id>
    <owner>Dusan Babich</owner>
  </device>
  <device>
    <description nil="true"></description>
    <id type="integer">4837</id>
    <identifier>Android_351751049564712</identifier>
    <organization-id type="integer">3569</organization-id>
    <owner>John Doe</owner>
  </device>
</devices>

Sending a Push

Depending on the platform, pushing a form to an organization’s device will have a different effect. On the BlackBerry platform, the red indicator light is illuminated, the unified inbox receives a message and the device status bar indicates an outstanding form for completion. On iPhone a message will popup if the app is closed. The app icon’s badge indicator will also reflect the amount of uncompleted pushed forms.

The first thing to realize about 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. Programatically, an XML payload is POST'ed as follows (be sure to set the content type to “application/xml”):

HTTP POST /clients/[device_identifier]/oneshots
HTTP POST /clients/Android_351751049564712/oneshots

The device_id url parameter is obtained from the Device Enquiry 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 a form is to view in the designer and then use the Export button to see it’s XML. Let’s continue using the example of the demo form, “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. 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. In this way, it would be very easy to send your sales staff a list of people to call on by pre-populating, for example, customer name, address, revenue etc. 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>

If you’d prefer to push oneshot forms using JSON, you can do this too.

As with the XML, you need to send your POST to:

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

And if you have 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",
        "group_1" : [
            { 
                "group_question_1" : "elderberries", 
                "group_question_2" : "figs"
            },
            { 
                "group_question_1" : "grapes", 
                "group_question_2" : "haricots"
            }
        ]
    }
}

Checking Outstanding PUSH Forms

In the event you want to enquire which forms are still outstanding for a device, simply issue a GET request as follows:

GET /clients/[device_id]/oneshots

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

GET /organizations/[organization_id]/oneshots

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

<?xml version="1.0" 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>
  </form>
</forms>

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 PUSHed Forms

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

DELETE /clients/[device_id]/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_id]/oneshots/destroy_all

Advanced – Pushing Images & GPS Co-ordinates

Sometimes it can be convenient to push binary data types into Pushed forms. For example, you may want to provide a base image for a sketch question, or supply a reference image. Any binary field can be pre-populated just as you would a regular field, but you have to Base64 encode the binary image data so it’s valid XML.

Images must be in JPEG format.

Pushing GPS co-ordinates for a location question enables you to pre-populate a location question. This is useful if you want to provide field workers with an address they can navigate to. 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.