Bulk Dispatching into Repeatable Sections

Available on all tiers:

• Instructions for Bulk Dispatching
• 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

About

Bulk dispatching uses a TrueContext 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

Download the Dispatch Template File

In the TrueContext Administration portal, navigate to the form you want to use to dispatch. If the form has been configured for dispatching, a Dispatch The term "dispatch" refers to the act of sending a form to a mobile user or customer. Typically, a dispatched form includes some information pre-filled to give the recipient context for the work to be done. Dispatch can be manual or automated (using a Dispatch Data Destination or the TrueContext REST API). button will be displayed on the page. 

On the following page (the web portal dispatching interface), select the BULK DISPATCH 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. Select the Download Active Dispatch CSV Template hyperlink and save the file to your computer.

About the Dispatch Template File

The screen capture below shows a sample dispatch template CSV file for a form containing a repeatable section A Repeatable Section is a subform that contains a set of related questions. The data captured is “repeating”, because the field user can complete the same subform more than once, which creates multiple entries.. 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 TrueContext 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 TrueContext 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 prefilled 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 TrueContext 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.

How to Use the Dispatch Template

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 TrueContext user who is to receive it on their mobile device. This is done by entering either the 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 prefill 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. 
  
  

Note:If you use a spreadsheet application to work with your dispatch data, be sure to save as CSV before uploading to the portal.

Dispatching Images

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 TrueContext from an earlier site visit or job estimate.

In order to dispatch images with the Bulk .CSV template, the images must be Base64 encoded. Format the image to dispatch as image/jpeg(or png)|/<base64 string here>. See below:

image/jpeg|/iVBORw0KGgoAAAANSUhEUgAAAAEAAAACCAYAAACZgbYnAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsIAAA7CARUoSoAAAAAQSURBVBhXY/gPBEwMDAwMAB32A/9omztwAAAAAElFTkSuQmCC

Data Formats and Supported Question/Data Types

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.

Info:The topic Supported Question and Data Types for Dispatching lists the data and question types that each dispatch method supports. It also describes the formatting requirements for specific types of questions, such as Barcode Scanner and Geolocation.