- Instructions for Dispatching from the Portal
- Download the Dispatch Template File for Your Form
- About the Dispatch Template File
- How to Use the Dispatch Template
- Data Formats and Supported Question/Data Types
Bulk dispatching uses a ProntoForms generated CSV template to allow administrators to send multiple dispatches out to mobile users at once. This article will discuss how to download, fill out, and submit the CSV file for dispatching into repeatable sections.
Note: Dispatching into nested repeatable sections is not supported.
Instructions for Bulk Dispatching
In the ProntoForms Administration portal, navigate to the form you want to use to dispatch. If the form has been configured for dispatching, a Dispatch button will be displayed on the page.
On the following page (the web portal dispatching interface), select the button. The Dispatch page contains options for downloading a dispatch template, and for re-uploading the template after dispatch data has been entered. See the screen capture below. Click the Download Active Dispatch CSV Template hyperlink, and save the file to your computer.
The screen capture below shows a sample dispatch template CSV file for a form containing a repeatable section. It has been opened in a desktop spreadsheet application. For convenience, the different data records contained in the example have been colored; the darker cells contain administrator-entered repeatable section data.
The template file is generated by the ProntoForms server, based on the setup of your mobile form. The anatomy of the file is outlined below.
Row 1 -- Basic Usage Instructions
These are simple instructions on usage of the template.
Row 3 -- Dispatch URL
Row 3 is for information only. It indicates the ProntoForms administration portal URL that was visited to generate the template. This URL is also used to upload the completed template file, with dispatch information entered, to the portal for distribution to your mobile users.
Row 5 -- Header Line to Distinguish Dispatch Recipient User Column Group (A & B) from Question Label Column Group (C and Higher)
This is the first of 2 header lines. This line indicates that columns A and B are used to specify the mobile users who will receive the dispatches. It also indicates that the columns beginning with column C are used to specify the optional answers that may be pre-filled in the dispatched form.
Row 6 -- Header Line to Indicate Specific Dispatch Recipient User Columns and Specific Question Label Columns
This second header line gives the details of use for each column in the CSV.
Row 7 and Higher-- Dispatch Data Rows
Row 7 is where the ProntoForms administrator begins to enter information for dispatching. When dispatching into a form with repeatable sections, there should be:
- One Username and User ID per dispatched form,
- Data to be dispatched into repeatable sections starting on the top row, with as many additional entries as the form allows beneath.
- Note: The only data that should be in rows after the first (user ID/Username) should be in repeatable questions. If there is additional data in cells that are not repeatable section data, the dispatch will fail.
A new dispatched form begins when a new Username and/or User ID are entered in columns A and B.
To compose the forms to dispatch to your mobile users, begin entering data in row 7 of your template.
For every dispatch, you must specify a ProntoForms user who is to receive it on their mobile device. This is done by entering either the ProntoUser user ID in column A or the username in column B. It is mandatory to have a value in either column A or B for each dispatched form. In fact, this is the only mandatory data for a dispatch -- columns C and beyond may be left blank if you do not wish to pre-fill any questions for the mobile user.
In the sample above, the administrator-entered dispatch data has been colored for clarity. The darker cells contain repeatable section data filled in by the administrator.
In the dispatch created by rows 7-11, the mobile user's user ID and username indicate the recipient. This dispatch pre-sets a value for each of the questions of the form, and adds five entries to the repeatable section that describes the parts required for the work order.
In the dispatch created by rows 12-13, the mobile user is indicated via the User ID in column A. This dispatch pre-sets a value for all the other questions in the form, and adds two entries to the repeatable section that describes the parts required for the work order.
In the dispatch created by row 14, the mobile user is indicated by username, and no question values are pre-set. It looks simple, but this is a valid dispatch.
Important things to note:
- Removal of Question Label Columns from Your Form Template is Allowed
The form used in this example is very simple. Longer and more complex forms will have more question labels displayed horizontally in additional columns. To keep your template simple and readable, you may wish to delete question columns for which you do not intend to pre-set values in dispatches. (Removal is not modification; the server will handle missing columns, but if data is provided that does not match a header, it will cause issues.)
- Re-use of a Generated Template is Allowed
The template is generated dynamically, based on the configuration of the selected form. Unless your form changes, you can re-use this template as many times as you want. If the questions or labels on your form do change, however, it is highly recommended that you download an updated template.
- Question Constraints Must be Honored in Dispatches
Attempts to pre-set question values which violate form constraints, like trying to set a phone number question with a person's name, will be rejected by the server.
- Dispatching into Nested Repeatable Sections is Not Supported
You cannot dispatch values into repeatable sections that are contained within other repeatable sections.
- Dispatching into Repeatable Section Footers is Not Supported
You cannot dispatch a value into the footer of a repeatable section.
If you use a spreadsheet application to work with your dispatch data, be sure to save as CSV before uploading to the portal.
Images can be dispatched to any attachment control: camera, sketch pad, or signature. This allows administrators to dispatch images that are specific to a particular job, like a site-specific floor plan, a chart for the mobile user to reference, or a sketch produced in ProntoForms from an earlier site visit or job estimate.
In order to dispatch images with the Bulk .CSV template, the images must be Base64 encoded. This is typically done programmatically, but it can also be done manually using an online tool like http://www.base64-image.de/. Format the image to dispatch as image/jpeg(or png)|/<base64 string here>. See below:
Not all question types are supported for dispatching. The generated template will not include columns for question types that aren't supported. Further, some question types have specific formatting requirements.
For details, please consult Data Formats and Supported Question and Data Types for Dispatching.