API Dispatching for Repeatable Sections

 

Note: This is a limited-release feature. It can currently be added to your forms by our Professional Services team. Please contact your ProntoForms account manager for more information.

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 a user’s mobile device. Most, but not all, data formats, question types and data types are supported for dispatching.

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.

URL Structure

api.prontoforms.com/api/[version]/data/dispatch.xml
api.prontoforms.com/api/[version]/data/dispatch.json 

Method

POST

Request Parameters

None.

 

Request Body

Required Parameters

Dispatching records that do not contain any question data is supported.  The dispatch request body must contain the following aspects. 

formId

Indicates the ID of the form which is used to render the form for the user.  Please note that this is the top-level form ID, and does not refer to the form iteration ID. 

userId or username

Indicates the user who will receive the dispatch. Only one of these is required.

For assistance in locating FormID and UserID values, refer to How to find the Form ID, Username and User ID in the Portal

Optional Parameters

The following dispatch message parameters are optional.  

dispatchToDraft

If the form you are working with is in a draft state and you want to dispatch using the draft (for development purposes), then set this value to true.  The default is false.  If this property is set to false, the active version of the form is used for the dispatch. 

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. Do not dispatch answers with special characters [*, &, #, >, <] as these are read as code and may cause errors.

repeat

Repeatable sections allow you to dispatch to a set of questions as many times as required. Use <answer type="Repeat"> to define a section of your dispatch as a repeatable section.

Note that a section can only be dispatched as a repeatable section when it is pre-defined in the form definition as a repeatable section.

row

When using repeatable section, the start and end of each repeated section must be defined using <row> and </row>.

Note that while it is possible to repeat a section infinite times in this way, keep in mind the maximum submissions size of the form when dispatching. 

Note: When using the API to dispatch data to a question that has collect additional answers enabled, 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.  

 

Standard Samples

Two sample dispatch messages are provided below, one in XML and one in JSON format.  The XML version illustrates a dispatch sent to an active form, with the dispatch recipient specified via the ProntoUser user ID.  The questions labelled as "firstName" and "lastName in the form definition are given preset values.  The JSON sample performs the same dispatch but assigns it through the user’s username rather than the user ID, and sends it to the draft version of the form rather than the active version.

XML

<dispatch>
 <formId>140001</formId>
  <userId>160002</userId>
  <data>
     <answer label="firstName">John</answer>
     <answer label="lastName">Smith</answer>
     <answer label="phone">8882824184</answer>
     <answer label="address">515 Legget Drive</answer>
  </data>
</dispatch>

 

JSON 

{
 "formId": "140001",
 "dispatchToDraft": "true",
 "username": "bjohnston",
 "data": [
   {
       "label": "firstName",
       "answer": "John"
   },
   {
       "label": "lastName",
       "answer": "Smith"
   },
   {
       "label": "phone",
       "answer": "8882824184"
   },
   {
       "label": "address",
       "answer": "515 Legget Drive"   
   }
 ]
}

 

Repeatable Sections

Repeatable sections allow a section of a form to be produced as many times as required in a business process, such as in an estimate when adding additional parts to an order.  In the form, each repeatable section will appear as a spreadsheet.

 

Repeatable Section Samples

Repeatable sections must be defined as <answer type=“Repeat”> in your dispatch, and each repeated set of questions must be framed with <row> and </row>.

Note that a section can only be dispatched as a repeatable section when it is pre-defined in the form definition as a repeat.

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

XML

<dispatch>
   <formId>142570035</formId>
   <userId>131911039</userId>
   <data>
       <answer type="Repeat" label="Address">
           <row>
               <data>
                   <answer label="Street No.">1722</answer>
                    <answer label="Street Name">Evergreen Terrace</answer>
                     <answer label="Status">Open</answer>
                   <answer type="Repeat" label="Tools">
                       <row>
                           <data>
                               <answer label="Item">Drill</answer>
                                 <answer label="Quantity">3</answer>
                                 <answer label="Size">3/4"</answer>
                                 <answer label="Status">Onsite</answer>
                           </data>
                       </row>
                       <row>
                           <data>
                               <answer label="Item">Ladder</answer>
                                 <answer label="Quantity">1</answer>
                                 <answer label="Size">8'</answer>
                                 <answer label="Status">Required</answer>
                           </data>
                       </row>
                   </answer>
               </data>
           </row>
       </answer>
   </data>
</dispatch>

 

JSON

{
"formID": "${FormID}",
"dispatchToDraft": "${dispatchToDraft}",
"userId": "${TeamAdminID}",
"data": [
{ "type": "Repeat",
"label": "Address",
"rows":[{
"data":[
{ "label": "Street No.", "answer": "1722"},
{ "label": "Street Name", "answer": "Evergreen Terrace"},
{ "label": "Status", "answer": "Open"},
{
"type": "Repeat",
"label": "Tools",
"rows": [{
"data": [
{ "label": "Item", "answer": "Drill"},
{ "label": "Quantity", "answer": "3"},
{ "label": "Size", "answer": "3/4in"},
{ "label": "Status", "answer": "Onsite"}
]
}]
"rows": [{
"data": [
{ "label": "Item", "answer": "Ladder"},
{ "label": "Quantity", "answer": "1"},
{ "label": "Size", "answer": "8'"},
{ "label": "Status", "answer": "Required"},
]
}]
}
]
}]
}
]
}

 

Response Body Samples

XML 

<dispatchResult>
  <dataId>123</dataId>
  <referenceNumber>20110902-123</referenceNumber>
</dispatchResult>

 

JSON

{
  "dataId": "123",
  "referenceNumber": "20110902-123"
}

Note: When using JSON, the raw number and boolean data types are accepted where applicable. Formatting all values as strings is also supported.

 

Sample cURL commands

curl -v -k -u user:password -X POST --upload-file FILENAME.xml https://api.prontoforms.com/api/1/data/dispatch.xml
curl -v -k -u user:password -X POST --upload-file FILENAME.json https://api.prontoforms.com/api/1/data/dispatch.json
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.

 

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 labels specified in the preset data list does not exist in the form.
InvalidAnswerData 400 Data could not be formatted to the data type of the question referenced by the label.
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.

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments