With this API, you can extend the basic Mobile Forms platform in two important ways:
Enable pre-population of form templates with values loaded from a database, for example.
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
- Device Enquiry
- Sending a Push
- Checking Outstanding PUSH Forms
- Revoking PUSHed Forms
- Advanced – Pushing Images & GPS Co-ordinates
All API requests to Device Magic must be made to the following URL (note the HTTPS):
where your organization_id is evident from the URL to your dashboard when browsing www.devicemagic.com/organizations/[organization_id]/.
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>
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:
You can also query for outstanding oneshots across all devices for your organization:
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:
where the [oneshot_id] is obtained by performing an enquiry as above.
To revoke all oneshots for a particular device, use:
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:
Note that the above format is the same as the location format received when forms are submitted, without the accuracy components.