Forms / Macros are an industry standard way of providing structured templates to ensure both consistency and reduced communication costs when messaging Drivers

Forms / Macros are an industry standard way of providing structured templates to ensure both consistency and reduced communication costs when messaging Drivers.
The following document provides detail on how to configure Forms on the Web Portal for use between Integrations, Web Portal, Vehicles and Drivers

Background on why Forms and Macros exist

Cutting costs may be the top priority of today's businesses, but streamlining processes is close behind. DriverTech helps with both. How? With forms. Our state-of-the-art functionality allows your dispatchers and drivers to communicate efficiently and cost-effectively.

Creating and Maintaining Forms via the Web Portal

Viewing details of existing Forms

Existing form details can be viewed by clicking anywhere on a Form Row within the table causing the detail to be populated into a read-only view the of edit fields

Creating New Forms

From the FleetWatcher menu, choose Management then Forms. You will be presented with a table of current forms (if any exist). You may select a current form from the table for viewing.
To add a new form, select Add Form button which is above the grid.


The opening screen has three fields and a check box that allow you to add a new form to your form library.   
New Form Information Screen:

Using the Form Definition Field

With your purpose identified and necessary fields specified, you are ready to build your form. The process is easy. Simply choose the types of fields you want included from the Fields Description section and customize them using options from the Field Definition Language (FDL) section.
Exhibit 5 is an example of how the process works. The instructions given in the Form Definition field define the final product shown in the Form Preview. The steps involved are explained below. By applying the pad option, embedded blanks, and the strip option to the field descriptions, you can design your form to match the look you want.

Steps for Creating a new Form

  1. Determine the order and placement of the fields for your form.
  2. Decide what parameters you want placed on the information for each field.
  3. Select appropriate Field Descriptions.
  4. Customize the Field Descriptions using FDL.
  5. Click Preview Button (bottom center) to see your form displayed in the preview pane.
  6. Make any appropriate changes to the Form Definition field so the final product is exactly the way you want it to be.
  7. Click Save button (bottom left).


You will be presented with the following confirmation. If you select "Update Trucks Immediately" (false by default) your instructing the system to push the new form out to all vehicles right now.
If you dont select "Update Trucks Immediately" then the new form will be communicated to the fleet on-demand or during each ELD's individual communication transaction.

Editing and Disabling Forms

To edit a preexisting form, select the desired form by clicking on it in the spreadsheet list, then click [edit] . Make the desired changes, then click [save]

You can also choose to disable a form. This will remove the form either from the drop-down for forms in the portal Mail application or on the in-cab unit, if it has been selected as an Inbound message. Click  [deactivate] to deactivate a form.


 

Field Definition Language (FDL) Specification

Forms are built using fields. In the Field Descriptions section of the guide, we outline all the fields available to you. In the Create a Form section, we show you how the process works.
In this section, we explain the Field Definition Language (FDL) used to customize your form fields to suit your purposes.
The table below summarizes the FDL Characters you use in your formulas to define input controls.
 

Form and Field Configuration Limitations

The Maximum Number of Forms (both Inbound and Outbound) is 127

The Maximum Number of Characters within a Form (the FDL which describes a form) is 4000 characters.

FDL Character Overview

FDL CharacterCharacter Application and Handling
" "Characters enclosed in double quotes become static text.
< >Fields enclosed in angle brackets are mandatory.
{ }Text that is book-ended by curly brackets is read-only.
[ ]Straight brackets automate the process of populating a field.
*The asterisk, or star symbol, hides the information inserted in a field.
#The pound sign represents a number (any number) in a mask-field formula.
?The question mark represents any alpha character in a mask-field formula.
~The tilde (or swung dash) can be used in a mask-field formula to represent any keyboard character.
+The plus sign is used in mask-field formulas to represent either plus or minus signs.
IThe upper-case letter I is used to designate unsigned integers.
iThe lower-case letter i is used to designate signed integers.
TUpper-case T designates text fields.
RUpper-case R establishes an auto-reply field.
LUpper-case L defines a list.

Defining the Size of  Input Fields

Many of the input boxes can be sized by placing the character width in parentheses just after the FDL character indicating the field type.

FDL DefinitionApplication
T(35)35 characters per field
L(10)10 characters per line

Maximum input character functionality

In addition, you can define the maximum number of characters that can be entered in a field. To use this feature, you must also use the size option. For example, to create a text field with a size of 20 characters and maximum input of 10 characters, you would use the following T(20:10).
The table below shows sample field widths and input maximums for the FDL field types that support the maximum input character functionality.

FDL DefinitionField WidthMax Input Characters

When a formula includes bracketed information, the term length may appear both inside and outside the brackets as highlighted by the superscript numbers in the sample format below:
T(length 1) [P=length 2 ,padChar,justification(Left,Right)]
The term functions as follows:

  • length 1 = Length reserved on the back end
  • length 2 = Length on the ELD

When length appears only once in a formula, the field width is the same for the back end as it is for the ELD.

T(10:8)108
L(6:2)62


FDL Field Detail

Field ModifiersFormat TypeExampleNotes

Standard Fields

Fields not defined as Mandatory or Read-Only work as regular input or description form fields. These are the most common and are defined below in this table. Any standard field can be modified to operate as a Mandatory or Read-Only using the following characters:

Mandatory Modifier

Fields enclosed in < > (brackets) become mandatory and all field types below support mandatory definition.
Drivers are required to complete these fields in order to send the form.
Only an entire field can be book-ended by brackets. A single field cannot be divided into mandatory and non-mandatory parts.

< field() ><T(10)>

Mandatory fields are obvious on a form only when they are described as mandatory, or when a user attempts to send a form without completing such a field and receives an error message.

TIP!
It is helpful (but not required) to provide information about which fields are Mandatory by including a note at the top of your form stating An * indicates a required field; then use the static text functionality to include an * next to each mandatory field

Read-Only Modifier

Fields enclosed in { } (curly brackets) become read-only and all field types below support Read-Only definition.
The driver is NOT be able to modify these fields.

{ field( ) }
{T(10)} There is no need to identify read-only text on your form. Should a driver attempt to change a read-only field, an error message appears to explain the field's status

Field Descriptions

Each field description includes the following information:

  • Field Type: Gives the field's function and explains how the field is used.
  • Format Type: Explains how the field is constructed.
  • Example: Shows the formula for applying the format. In some cases, more than one option is possible.
  • Example Result: Shows a sample of how the field will appear on the final form (when applicable). May also include hints for using the function.

The descriptions are designed for modularity. We meet with you to assess your requirements, bundle the options you need together, then provide you with the formulas for the other options so you can modify your set as your company evolves.
Noted below are characteristics that are common to multiple formulas and helpful in achieving the end results you want.

  • Pad Option: If the text for a field contains fewer characters than the field allows, the pad option lets you fill out the field with whatever character-type you choose.
  • Embedded Blanks: This feature allows you to insert blank spaces in predetermined positions.
  • Strip Option: With this feature you can remove any symbolic characters (e.g., $, @, #, /, *) from the text.

Also common to multiple formulas are brackets. When a formula includes brackets, the term length may appear both inside and outside the brackets as highlighted by the superscript numbers in this formula: T(length 1)[P=length 2,padChar,justificationLeftRight]. The term functions as follows:

  • length 1: Length reserved on the back end
  • length 2 : Length on the ELD

When length appears only once in a formula, the field width is the same for the back end as it is for the ELD.

Field TypeFormat TypeExampleExample ResultNotes

Static Text (Comments)

Field descriptions are created using Static Text. Anything enclosed by " " (double quotes) is displayed as static text on the form. Static text can be composed of any characters (alpha, numeric, or symbols)
"Static text here""Name"Name

Name fields composed of static text are closed fields.

Generally, static text is used to identify the form (title) and delineate sections (heads and sub-heads), to explain the form's use, and to indicate the information to be provided in associated open fields






Free Form (Text Box)

Free-form text boxes accept alphabetic, numeric, or special characters configured in a variety of ways. These fields can store data padded with trailing blanks to fill out the field to its full length when the pad option is used.
Free-form text boxes offer users great flexibility, which is both their advantage and their disadvantage. Use other fields whenever possible in order to better control responses.

T(length)T(10)ABCDEFGHIJ
T(length:MaxChars)T(10:8)12345678_ _
T(length:MaxChars:height)T(30:200:10)
This is a multi-line text field. In the example, 30 equals the width of the text box, 200 equals the maximum number of characters allowed in the box, and 10 equals the length of the box.
T[P=length, padChar, justificationLeftRight]T[P=10, ,R]
T[P=10, ,L]

_ _ _ ABcd123
ABcd123_ _ _







Mask Field (multi-purpose)

This is the most flexible do-it-all field. Use the following symbols to define the content for the mask field:

  • # represents any number.
  • ? represents any alpha.
  • ~ represents any character.
  • + represents + or − signs.
All other characters are hard-coded static characters that are embedded in the field
T[M=maskChars]T[M=###]123

T[M=+###]-123Using value: -1234

T[M=???]ABCUsing value: ABCDE

T[M=~~~~~~~~~~]A1,?+=#'(bUsing value: A1,?+=#'(b

T[M=###???~~~]123ABC*,$Using value: 123ABC*,$





Mask Field Options (deprecated)

Warning! These definitions are not functional on all platforms. 

Using this alternate format you can pad the field with a specific character or optionally strip characters out when the strip option (S) is used at the time the form is sent to the data center.

T[M=padChar,maskChars | stripOption]T[M=0,##-??-~~]01-0a-0*

T[M=###.# | S]123.4Using value: 1234

T[M=???-?? | S]ABC-DEUsing value: ABCDE





Numeric / Decimal

This field accepts number only, and they are entered from right to left.
If the numbers to the right of the decimal are specified, a decimal point (.) is added.
The remaining character spaces are populated with specified pad characters.
A blank or space is the default pad character.
The user defines which character is used for padding, and that character is placed in the slot at the end of the formula.

T(length)[F=N,numbers to the left of decimal,numbers to the right of decimal, padChar]

T[F=N,3,2, ]

123.45


T[F=N,3,0, ]_12
T[F=N,5,0,0]00123
T[F=N,3,3]_ _1.234





Alpha

This field accepts only alpha characters.

T[M=?...]T[M=?????] ABCDE





Unsigned Integer

This field accepts numbers only. Sign characters (+ or −) are not accepted.
Trailing or leading spaces are allowed with "space" (' ') as the pad character.

T(length)[F=I | P=length,padChar,justificationRightLeft]T(10)[F=I | P=10, ,L]12345_ _ _ _ _
T(10)[F=I | P=10, ,R]_ _ _ _ _12345
T(10)[F=I | P=10,0,R]0000012345





Signed Integer

This field accepts numbers and an optional positive or negative sign (+ or −) as the leading character.
Trailing blanks are accepted, but embedded blanks are not.

T(length)[F=i | P=length,padChar,justificationRightLeft]T(10)[F=i | P=10, ,L]−12345_ _ _ _
T(10)[F=i | P=10, ,R]_ _ _ _−12345





Full Field Integer

This field accepts numbers only. Leading and trailing spaces are not accepted.
The user can either fill in the entire field, or leave the entire field blank.

T[M=###...##]T[M=#####]12345





Monetary


This field has a dollar sign ($) fixed as the first character.
The field accepts numbers and a decimal point with two digits.

T[M=$####.##]T[M=$###.##]$_ 7.45 _
T(length)[F=N,numbers to the left of decimal,2,padChar]T(6)[F=N,3,2, ]_ _7.45





Date

This field accepts numbers in a long date format (mm/dd/yyyy).
The entire field must be filled in.

TIP!
For all Date fields (Long, Mid, or Short), the digits sent OTA are determined by the field definition.
For example, a field that displays at the mobile unit as mm/dd/yyyy is sent OTA as mmddyyyy if the field is defined with the strip option, or as mm/dd/yyyy if the strip option is not applied.


Also See: Auto-Fill DateTime

T(length)[F=D | S ]

  • F = Format
  • D = Long Date
  • S = Strip slash (optional)
T(10)[F=D]10/22/1995Long Date: This field accepts numbers in a long date format (mm/dd/yyyy). The entire field must be filled in.
T(10)[F=D | S]10221995Long Date without Slash

T(length)[F=d | S ]

  • F = Format
  • d = Mid Date
  • S = Strip slash (optional)
T(8)[F=d] 10/22/95Mid Date: This field accepts numbers in the date format (mm/dd/yy).
If the field is not filled, six blanks with two slashes (_ _/_ _/_ _ ) are stored, or if the strip option is applied, six blanks ( _ _ _ _ _) are stored.
T(8)[F=d | S]102295Mid Date without Slash

T(length)[F=d | S ]

  • F = Format
  • S = Short Date  
  • S = Strip slash (optional)
T(5)[F=S]04/25Short Date
T(5)[F=S | S]0425Short Date without Slash





Time (24 hr clock)

This field accepts a 24-hour time entry in the hh:mm format.

T(length)[F=C | S ]

  • F = Format
  • C = Clock
  • S = Strip colon (optional)
T(5)[F=C] 21:45Time (24hr)
T(5)[F=C | S]2145Time (24hr) without Colon





Date and Time




See: Auto-Fill DateTime





Library Content (File reference)

This field is used to link library content to a form. This field is displayed as a button on a form and when pressed it launches the content in the library.

T(length:MaxChars)[F=BL]T(10:30)[F=BL]

The content of the field contain both the file name to be launched within the library and an optional description. The file name is separated from the optional description with a '~' character (i.e. <file name>~<description>). If no description is provided then the file name will be used for the button description. Here are some examples:

  • xyz.pdf
  • xyz.pdf~Press Button





Phone # (w/area code)

This field accepts a phone number entry with an area code in the format nnn-nnn-nnnn

T[M=### - ### - ####]T[M=### - ### - ####]123-456-789





Item List

This field accepts any item belonging to an associated list of items.
An item is a string of characters which cannot include embedded commas.
An item list actually occurs as part of the form definition and displays as a drop-down box.
An item list may contain an arbitrary number of items.

TIP! Various pre-configured lists of commonly used terms are available for your use in various list types can be referenced using the following values:

  • L1: Y, N

  • L2: Weekdays - Sunday, Monday, Tuesday, ...

  • L3: Months - January, February, March, April, ....

  • L4: US State Abbreviations - AL, AK, …, WY

  • L5: Canadian Province Abbreviations - AB, BC, …,YT

  • L6: Mexican State Abbreviations - AG, BJ, …, ZT

  • L7: Combined list of US State, Canadian Province, and Mexican State abbreviations

L(length:Item1, Item2 ,ItemN)

Warning! Value of length must be at least the
maximum character length of the longest item in the collection

L(6:1234,ABCD,AA11BB)

A list of trucks might include items such as Peterbilt, Volvo, or Freightliner.
Character strings can be alpha or numeric, or a combination of both.

Item List L1: Y or N

This field holds a single character: either Y or N. The field can be constructed to show one or the other as the default

T(length)[F=L1]T(1)[F=L1]YY/N via defined list type: L1

Item List L2: Weekday Abbreviation

This field accepts a three-character day abbreviation (Sun, Mon, Tue,…, Sat)

 T(length)[F=L2]T(3)[F=L2] Sun Weekdays via defined list type: L2

Item List L3: Month Abbreviation

This field accepts a three-character month abbreviation (Jan, Feb,…,Dec)

 T(length)[F=L3]T(3)[F=L3] Jan Months via defined list type: L3

Item List L4:  US States Abbreviation

This field accepts a two-character US State abbreviation (AL,AK,…,WY)

 T(length)[F=L4]T(2)[F=L4] AL States via defined list type: L4

Item List L5: Canadian Province Abbreviation

This field accepts a two-character Canadian Province abbreviation (AB, BC,…,YT)

T(length)[F=L5]T(2)[F=L5]ABCanadian Provinces via defined list type: L5

Item List L6: Mexican State Abbreviation

This field accepts a two-character Mexican Province abbreviation (AG,BJ,…,ZT)

T(length)[F=L6]T(2)[F=L6] AGMexican Provinces via defined list type: L6

Item List L7: North American State or Province Abbreviation

This field accepts a two-character US State, Canadian Province, or Mexican State abbreviation

 
T(length)[F=L7]T(2)[F=L7] ALNorth American State or Province via defined list type: L7





Auto-Fill or Auto-Population of Data

Its often valuable to more accurate to have form data automatically populated instead of requiring manual entry. Below are various data elements which support auto-population

Odometer (in miles)

This formula automatically populates a text field with the truck's lifetime odometer reading at the time the form is pulled up.
The odometer reading can be displayed with or without the MI (miles) designation (#o = with, #O = without)
T(length)[#O | P=length,padChar,left or right justification]
  • #O:<Odometer>
  • #o:<Odometer> MI
T(11)[#O]75000.0
T(11)[#o]75000.0 MI
T(11)[#O | P=11,0,R]000075000.0
T(11)[#o | P-11,0,R]000075000.0 MI

Fuel (in gallons)

This formula automatically populates a text field with the truck's lifetime fuel consumption at the time the form is accessed.
Fuel consumption can be shown with or without GAL appended (#f = with, #F = without)
T(length)[#F | P=length,padChar,left or right justification]
  • #F:<Total Fuel>
  • #f:<Total Fuel> GAL
T(11)[#F | P=11,0,R]0000050000.0
T(11)[#f | P=11,0,R]0000050000.0

Date and Time

This formula creates a text field that automatically populates with the current date and time at the time the form is accessed.

Warning! The value in this field is not validated after being set or modified.
If using this to capture DateTime from the Driver you may consider making the field ReadOnly which will cause it to be populated when the form is selected, or re-selected, (to set 'current dateTime') and not allow modification thereafter

T(length)[#T]T(20)[#T]
T(20)[#T | S]
17:02 04/07/2009
170204072009
Date and Time (24hr)
Date and Time (24hr) without Colon, Space, or Slash
D[#T]D[#T]
D[#T | S]
04/07/2009
04072009

Long Date
Long Date without Slash

d[#T]d[#T]
d[#T | S]
04/07/09
040709
Mid Date
Mid Date without Slash
S[#T]S[#T]
S[#T | S]
04/07
0407
Short Date
Short Date without Slash
C[#T]C[#T]
C[#T | S]
17:02
1702
Time (24hr)
Time (24hr) without Colon

Location

This formula defines a text field that automatically populates the vehicle's current position by latitude and longitude.

T(length)[#P]T(20)[#P]40.7293,-111.9654

Trailer(s) - BiDirectional updates to and from HOS

This formula defines a text field that automatically populates the vehicle's current hooked trailer(s). Up to 3 possible hooked trailers.

This formula defines a text field that automatically populates the last supplied Trailer(s). The Trailer(s) value comes from either the last entered Trailer(s) Value on the drivers HOS logs, or the last form/macro with a Trailer(s) auto-fill field. The value comes from either HOS logs or a form/macro depending on which occurred last. You will need device software 6.07.xx or newer for this functionality to work.

T(length)[#H1]

T(length)[#H2]

T(length)[#H3]


T(length)[#H]

T(10)[#H1]

T(10)[#H2]

T(10)[#H3]


T(30)[#H]

13000

23000

33000

 

13000,23000,33000

Trailer 1

Trailer 2

Trailer 3


All 3 trailers or up to 3 trailers (if exist) comma separated

Trailer(s) - UniDirectional update of HOS

This formula defines a text field that saves/updates trailer(s) entered by a driver. Up to 3 possible hooked trailers.

Unlike its BiDirectional counterpart, this field will not retrieve an updated value from HOS and can only be updated by the Driver. Also see the "Auto-Fill Variables" section below.

T(length)[@H1]

T(length)[@H2]

T(length)[@H3]


T(length)[@H]

T(10)[@H1]

T(10)[@H2]

T(10)[@H3]


T(30)[@H]

13000

23000

33000

 

13000,23000,33000

Trailer 1

Trailer 2

Trailer 3


All 3 trailers or up to 3 trailers (if exist) comma separated

BOL (Bill of Lading / Shipping document number) - BiDirectional updates to and from HOS

This formula defines a text field that automatically populates the last supplied BOL. The BOL value comes from either the last entered BOL on the drivers HOS logs, or the last form/macro with a BOL auto-fill field. The value comes from either HOS logs or a form/macro depending on which occurred last. You will need device software 6.07.xx or newer for this functionality to work.

T(length)[#B]

T(20)[#B]

B1O1L

B1O1L,B2O2L,B3O3L
Single
or
Multiple BOL(s) values

BOL (Bill of Lading / Shipping document number) - UniDirectional update of HOS

Unlike its BiDirectional counterpart, this field will not retrieve an updated value from HOS and can only be updated by the Driver. Also see the "Auto-Fill Variables" section below.

T(length)[@B]T(20)[@B]B1O1L

B1O1L,B2O2L,B3O3L
Single
or
Multiple BOL(s) values





Auto-Fill: Variables

An auto-fill variable is typically used to transfer value(s) between a forward and return form. For example: if the load# that is on the forward form needs to be populated on the return form, then an auto-fill variable can be used to facilitate this.

Storing data

Data is 'stored' into an specific position of an array using the @ char
For example, to store data into position 1 of the array you would use @1, for position 4 you would use @4

T(length)[@n]T(20)[@1]

Stores form field value into array element 1

Storage Array is limited to 30 elements beginning at 1: @1, @2, @3, ... @30

Retrieving data

Data is 'retrieved' from a specific position of an array using the # char
For example, to retrieve data from position 1 of the array you would use #1, for position 4 you would use #4

T(length)[#n]T(20)[#1]

Retrieves value from array element 1 into form field

Storage Array is limited to 30 elements beginning at 1 and data retrieved using the # char: #1, #2, #3, ... #30

Note:

  • You can retrieve the value (#n) stored in a variable to more than one field.
  • You do not have to match field types when retrieving variables, however less problems will arise if they do match. For instance if you store a date fields value in a variable and retrieve it in a text field this is acceptable. However some combinations are not possible:
    • Date field to integer
    • Text field to integer (except if the value is a number)
    • Etc.





Auto-Reply with Specific Macro/Form

This form definition syntax makes it possible to automate part of the information on a driver's reply form.

[R=<form#>][R=20]

<form#> is the DriverTech inbound form number.
This is not the Customer Form Number. You can obtain the DriverTech form number via the "Edit Forms" screens in FleetWatcher or in the Web Services response to an Insert or update

This form definition syntax imposes itself on a driver's response.
The reply automatically reflects the information designated by the <form#> parameter (such as the "DriverTech inbound form number 20" in the example above).
This parameter must exist for the auto-reply within the form to work

click to enlarge images

Via Webservice API - Admin Service:

Via Web Portal - Management -> Forms:







Related articles