Skip to main content

Dispatch a Form with the REST API using Form Tags

  • Updated

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>

[top]

 

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: 

  1. Initiate a Dispatch Job.  This will queue the request in the ProntoForms system.
  2. 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)
  3. 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.

[top]

 

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.

UserAlias

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

[ top ]

 

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.

[ top ]

 

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.

[ top ]

 

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.

[top]

 

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

[ top ]

Related articles

Comments

0 comments

Please sign in to leave a comment.