Forms

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:

1. Create fields and set validation rules via App Manager, this is the most common approach

2. Dynamically build the form with the Forms API

Key Components

• name : The name of the form

• fields : 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., specific SCAN-MODE configurations).

• 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 as part of the form. This can be used to ensure document scan throughout workflow

• BARCODE : This field type allows a value to be either entered manually, similar to SINGLE-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_javascript for 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 run validation_rule_javascript if 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

To ensure security and accuracy, server validation occurs on your integration server instead of the user’s device. This process verifies the user’s input. For example, it can confirm a trailer number or check if a load remains active.

Server Validation Logic Flow

When server validation is active, the form submission process becomes a two-stage transaction:

• Provisional Stage: The app sends the data to your server, and displays a loading spinner to prevent the user from making any changes while the data is being verified.

• Finalization Stage: The app will behave in one of two ways based on the HTTP response from your server.

  • 422 Response: Reopens the form for corrections

    NOTE: You may provide your own custom error messages for invalid responses.

  • 200 Response: Locks the form and sends the final record

Validation Status Definitions

In the final message delivery, the server_validation_status field tells you how the data was verified:

NOTE: enable_telematics_data is ignored during the validation request to keep the payload light. Telematics only attaches to the final delivery.

Resources

API

• Forms

• Outbound Messaging

• Inbound Messaging