About

Form tags are a way to make groups of forms that are matched to a particular tag. ProntoForms allows dispatching by form tags, allowing an external system to dispatch to all forms tagged with a particular phrase. This does not require knowing the form IDs, meaning:

One-time setup for enterprise backend systems - set up a dispatch to a single tag.

Pronto Admins can add the tag to more forms, edit forms that have the tag, and move forms without needing to change the dispatch configuration.

Before You Begin

Before attempting to dispatch a form, please ensure that the pre-requisite configurations are in place by reviewing the dispatching documentation.

Dispatch a Data Record to a User

This method sends a dispatch message to the ProntoForms server, which in turn will dispatch that record to the ProntoUser.

Note that the response message to a successful dispatch will include the unique ID of the created record. If your business process requires that a dispatched record may need to be subsequently "undispatched" (deleted from the recipient's device), your API application should store this ID for use in the data record deletion API call.

enforceStrictLabelsWhen dispatching to a number of forms based on form tag, it's possible that some questions may not be common between forms. e.g. the forms sharing the same tag may have the following labels:Form A: Date, Location, Customer Name, License #Form B: Date, Location, Customer NameForm C: Date, Customer NameWith enforceStrictLabels set to false, Form C will only receive Date and Customer Name, and ignore the missing labels, resulting in a successful dispatch to Form C.This is set to false when dispatching by tag, meaning that missing question labels will be ignored and dispatches containing extra question labels will succeed. If you wish to enforce label matching for dispatching by tags, set this to true.

suppressPushUse this if you wish to suppress the push notification of the dispatch to your users.

Note: When using the API to dispatch data to a question that has been configured to "collect additional answers," the additional answers will NOT be automatically populated in the form. If it is essential that these values are pushed, it is up to the dispatcher to include the data in the dispatch.

Samples

Two sample dispatch messages are provided below, one in XML and one in JSON format.

Important Note: Replace user with your API Key ID and password with your API Key secret. Also, replace FILENAME with the name of your actual file which should be formatted as per the XML or JSON request body samples above.

URL Structure

Method

GET

Sample Response Body (XML)

In this example, all the dispatches were successful. Five different forms received dispatched data based on dispatching to tag1. The response body also shows what question labels were dropped (in this case, none).

Data Record IDs are returned in the response body (under <dataID>[ID]</dataID>)

It is possible for dispatch to one form to work, and another to fail. This can be the result of:

Incorrect user permissions: Users can only receive dispatches for forms they have "can submit" permissions to. As form tags can include forms from multiple FormSpaces, users may not have "can submit" permissions to all of the forms within a tag. They will only receive the dispatched forms that they have permissions to.

enforceStrictLabels: If set to true when dispatching into multiple forms where Form 1 may have all the question labels, but Form 2 does not, the dispatch will succeed to Form 1, but fail to Form 2.

The response body also tells you which question labels were dropped, or did not receive data due to mismatch or being missing.