Overview
Forms allow you to collect structured data from users through a series of defined fields. They are integrated throughout the app and can be created in App Manager or managed via the Forms API.
Forms enable users to advance workflow, scan documents, communicate with back office and complete tasks.
How it Works
Forms deliver user input to your Messaging web service. It is important to understand the relationship between the form definition (how it looks) and the form instance (the data being sent).
There are two ways to manage and define forms:
Create fields and set validation rules via App Manager, this is the most common approach
Dynamically build the form with the Forms API
Key Components
name: The name of the formfields: A required array of field types
Field Types
You’re able to build forms with 20 different field types, including the following:
SINGLE-LINE: The standard text input field. This renders a text box in the app that restricts the user to a single line of data (disallowing newlines). Beyond simple text entry, this field type is frequently used as a versatile "container" for data that is hidden from the driver or populated via background JavaScript logic (e.g., specificSCAN-MODEconfigurations).MULTI-LINEPICK-LIST: A multi-select option list.LOAD-LIST: A populated list of active loads, containing the display identifier and customer name.AUTOMATIC-CURRENT-LOCATION: Capture user’s current location at the time of sending the form.RATING: Displays a one to five star scale.FORM-SCAN: Scan a document or capture a photograph as part of the form.NOTE: Mobile app versions 1.64 and later support up to 25
FORM-SCANfields per form.BARCODE: This field type allows a value to be either entered manually, similar toSINGLE-LINE, or scanned from a barcode using the phone’s scanner. The following barcode types are supported:1D Barcodes: EAN-13, EAN-8, UPC-A, UPC-E, Code-39 (without check digit), Code-93, Code-128, ITF, Codabar
2D Barcodes: QR Code, Data Matrix, PDF 417
IMPORTANT: To ensure accuracy, we highly recommend all barcodes have a check digit. Avoid the use of “barcode fonts” for generating barcodes, as these almost never include a check digit. At this time, only a single barcode can be scanned in one field.
Launching and Receiving Form
Once defined, a form must be launched by one of the following elements or functions:
Actions
Custom Screens
Menu
Dashboard
Scan Flow
Messaging
When the form is submitted by a user, it is should be received by your Messaging web service.
Form Messages
Users typically send form messages from specific app contexts, such as an active load or stop. This approach saves time by automatically populating relevant information so the user does not have to search for the appropriate form.
For more detailed information, please refer to our dedicated Messaging Guide.
Validation
Validation ensures that the data captured in a form is accurate, complete, and formatted correctly before it reaches your back-office systems. Our system utilizes two distinct validation methods: In-line and Server.
IMPORTANT: For versions 1.62 and below, enabling server-side validation on a workflow action disables
validation_rule_javascriptfor all fields on the form. For versions 1.63 and newer, if server-side validation is unable to be run due to the driver being offline or the app not being able to reach the server, then the app will attempt to runvalidation_rule_javascriptif provided.
In-line
In-line validation provides instant feedback directly on the user's device, actively guiding them and preventing data entry errors before submission. This is done via these optional properties:
visibility_javascript: A JavaScript function that will dynamically show or hide subsequent fields based on conditional requirements.validation_rule_javascript: A JavaScript function that validates the content of a specific form field.
NOTE: You may provide your own custom error messages for invalid responses.
Server Validation
Server validation verifies form data on your integration server instead of the user's device, so submissions are checked against your back-office systems before they are finalized. For example, you can confirm a trailer number or check that a load is still active.
For more information, see our Server Validation Guide.