Related Links
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.
Read more about data formats and supported question and data types for dispatching.
URL Structure
api.prontoforms.com/api/[version]/data/dispatch/bytag.xml
api.prontoforms.com/api/[version]/data/dispatch/bytag.json
Method
POST
Request Parameters
<dispatchByTag>
<formTag>[formTag]</formTag>
</dispatchByTag>
How to Check the Status of a Dispatch
Dispatching via tag is handled asynchronously by the ProntoForms system, meaning the job is not handled instantly but added to a queue. To check on the status of a dispatch:
- Initiate a Dispatch Job. This will queue the request in the ProntoForms system.
- Loop to check the status of the Dispatch Job. Continue checking until the status indicates the dispatch is complete. (Note: Each status check request counts toward your team's daily maximum)
- Check the success indicator of the Dispatch Job. If the job completed successfully, your dispatched user can proceed as normal. If it failed, an error message will indicate what went wrong.
Request Body
The dispatch request body must contain the following aspects:
formTag
Indicates which form or group of forms to dispatch to.
userId or username or userAlias
One of these values must be provided to indicate the user who will receive the dispatch. It will take the first valid value given (User ID, Username, and then User Alias).
For assistance in locating these values, refer to How to find the Form ID, Username and User ID in the Portal.
For assistance in locating and/or setting up user aliases, refer to Setting Up User Aliases.
While UserID and username are both single-entry aspects, user aliases use a system:user alias pair. This means that both must be present in the dispatch request to function correctly.
<userAlias> <system>ExampleSystem</system> <alias>JohnSmith</alias> </userAlias>
Optional Parameters
The following dispatch message parameters are optional. Dispatching records that do not contain any question data is supported.
data
The data section is used to pre-fill the questions of the form with answers for the dispatch. All answer data must be contained within the data section of the dispatch message.
answer
Use 1 or more "answer" properties in your dispatch message to pre-fill questions in the dispatched form. Please keep in mind the guidelines for Data Formats and Supported Question and Data Types for Dispatching.
enforceStrictLabels
When 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 unique IDs:
Form A: Date, Location, Customer Name, License #
Form B: Date, Location, Customer Name
Form C: Date, Customer Name
With enforceStrictLabels set to false, Form C will only receive Date and Customer Name, and ignore the missing unique IDs, resulting in a successful dispatch to Form C.
This is set to false when dispatching by tag, meaning that missing unique IDs will be ignored and dispatches containing extra unique IDs will succeed. If you wish to enforce label matching for dispatching by tags, set this to true.
Find more information on Unique IDs here.
suppressPush
Use 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.
XML
<dispatchByTag>
<username>apidispatchform@formsqa.com</username>
<suppressPush>false</suppressPush>
<dispatchToTags>
<formTag>tag_3</formTag>
</dispatchToTags>
<data>
<answer label="Customer Name">John Smith</answer>
<answer label="License#">0508618462109</answer>
<answer label="Location">Workshop 1</answer>
</data>
</dispatchByTag>
JSON
{
"username": "apidispatchform@formsqa.com",
"suppressPush":"false",
"dispatchToTags":["tag_3"],
"data":
[
{"label": "Customer Name", "answer": "John Smith"},
{"label": "License#", "answer": "0508618462109"},
{"label": "Locaiton", "answer": "Workshop 1"}
]
}
Sample cURL Commands
curl -v -k -u user:password -X POST --upload-file FILENAME.xml https://api.prontoforms.com/api/1.1/data/dispatch/bytag.xml
curl -v -k -u user:password -X POST --upload-file FILENAME.json https://api.prontoforms.com/api/1.1/data/dispatch/bytag.json
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.
Response Body Samples
XML
<dispatchByTagResult>
<identifier>3164117011</identifier>
</dispatchByTagResult>
JSON
{
"identifier": "3164117007"
}
Note: When using JSON, the raw number and boolean data types are accepted where applicable. Formatting all values as strings is also supported.
Troubleshooting
If your API call was successful, but you do not receive a data record on your team, or dispatch to the appropriate user inbox, you can check for errors:
URL Structure
api.prontoforms.com/api/[version]/data/dispatch/bytag/[Request Identifier].xml
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 unique IDs were dropped (in this case, none).
<dispatchByTagStatus>
<complete>true</complete>
<success>Success</success>
<dispatchByTagResultDetails>
<dispatchByTagResultDetail>
<returnCode>Success</returnCode>
<formId>141121024</formId>
<formName>Form (tag1)</formName>
<dataId>181283014</dataId>
<referenceNumber>20160929-13858018-181283014</referenceNumber>
<droppedLabels/>
</dispatchByTagResultDetail>
<dispatchByTagResultDetail>
<returnCode>Success</returnCode>
<formId>141121026</formId>
<formName>Form (tag1,tag_3)</formName>
<dataId>181283015</dataId>
<referenceNumber>20160929-13858018-181283015</referenceNumber>
<droppedLabels/>
</dispatchByTagResultDetail>
<dispatchByTagResultDetail>
<returnCode>Success</returnCode>
<formId>141120028</formId>
<formName>Form (tag1,tag-2)</formName>
<dataId>181283013</dataId>
<referenceNumber>20160929-13858018-181283013</referenceNumber>
<droppedLabels/>
</dispatchByTagResultDetail>
<dispatchByTagResultDetail>
<returnCode>Success</returnCode>
<formId>141121027</formId>
<formName>Form (tag1,tag-2,tag_3)</formName>
<dataId>181283016</dataId>
<referenceNumber>20160929-13858018-181283016</referenceNumber>
<droppedLabels/>
</dispatchByTagResultDetail>
<dispatchByTagResultDetail>
<returnCode>Success</returnCode>
<formId>141121029</formId>
<formName>Form (tag1,tag-2,tag_3)</formName>
<dataId>181283017</dataId>
<referenceNumber>20160929-13858018-181283017</referenceNumber>
<droppedLabels/>
</dispatchByTagResultDetail>
</dispatchByTagResultDetails>
</dispatchByTagStatus>
Note:
- 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 unique IDs, but Form 2 does not, the dispatch will succeed to Form 1, but fail to Form 2.
- The response body also tells you which unique IDs were dropped, or did not receive data due to mismatch or being missing.
Error Codes
Error Code Response Header |
HTTP Response Code |
Description |
InvalidDataException | 400 | Data did not meet the requirements specified in the form. |
DataLabelNotInForm | 400 | One of the unique IDs specified in the pre-set data list does not exist in the form (if using enforceStrictLabels). |
InvalidAnswerData | 400 | Data could not be formatted to the data type of the question referenced by the unique ID. |
DispatchToUnauthorizedUser | 416 | You have attempted to dispatch to a user who does not have access to the form. |
DispatchToArchivedForm | 416 | You have attempted to dispatch to an archived form |
DispatchNotAllowed | 416 | This form is not configured to allow dispatch. You must choose a Form Initiation Method of 'Dispatch' or 'Both'. |
DispatchFormVersionNotFound | 404 | The form does not have a version in the specified state (Active or Draft). |
DispatchFormNotFound | 404 | A form with the specified identifier could not be found. |
DispatchUserNotFound | 404 | A user with the specified identifier could not be found |
Comments
0 comments
Please sign in to leave a comment.