ASR Solutions

Please note that Eleos also has their own Forms documentation at https://docs.eleostech.com/docs/guide-forms

Overview

This document is intended to show off customization options using Eleos forms. This will touch on the form fields our integration checks when processing, form validation, visibility JavaScript, form emails, and other uses of forms and their fields. It will also specify which form field customizations are exclusive to standard form messages, and form field customizations exclusive to forms that require associated document scans.

Generic Form information 

Forms are created in Drive Axle and are typically linked to Actions to be completed by a driver. We can add form fields to the form, and that data is sent to our integration when the form is completed. Based on specific fields, our integration can process these fields and respond to them accordingly. This document will touch on some of the specific fields we utilize when processing a form, as well as some of the settings that correspond to the functionality that occurs during processing.

Trailer management 

Using Eleos forms, we can manage telematics trailers by either attaching trailers in Geotab that aren’t currently attached or removing trailers that are currently attached. There are a few key settings in the integration found in the appsettings.json file that control whether this behavior occurs:

By default, the CurrentTrailerFormKey is set to “TRAILER-NUMBER”, meaning that we will search for any fields on the form that start with “TRAILER-NUMBER”. Implementors should add fields to a form that contains the CurrentTrailerFormKey, with a number attached to it. For example, “TRAILER-NUMBER1” and “TRAILER-NUMBER2” will be pulled if the field name that matches the first part of the code.

For more information on Trailer syncing, please see our documentation on Geotab - Trailer Logs.

Form Validation 

When a form is submitted with an associated action that is configured for “Server Validation”, we use server-side validation to ensure that the configured fields on the form are set to what we expect they should be before the form is able to be submitted. This server-side validation calls the ELEOS.usp_ValidateMessage procedure (and possibly the ELEOS.usp_ValidateMessage_Custom procedure if existing within your database and SQL contracts are implemented), which is used to return any issues with the form.

If the procedure returns results that indicate an error and correspond to a field code on the form, the validation request will fail and alert the driver with a custom error message that there are issues with the specific fields on the form that must be addressed before it can be submitted.

Server-side validation form customizations are exclusive to standard form messages associated with “New Message” type actions. 

For more information regarding form validation, please review the Eleos - Messaging Server Side Validation document that goes more in depth on the validation process.

Visibility JavaScript 

On Eleos forms, there is a property called “Visibility JavaScript” that can contain some JavaScript to determine if specific fields on the forms are visible to the driver. Using this, we can do things like use JavaScript to show a specific field that was previously hidden. For more information, please review the Drive Axle - How to Create Dynamic Fields in Eleos that discusses how to implement, examples, and more.
 

The following is an example of the “visibility_javascript” property pulled from a form using the Eleos API. The goal is to return true or false for a field name, which determines if the field should or should not be visible.

Form Emailing & Document Processing  

When configured, form submissions can be converted into an email with customizable fields. If a form submission includes scanned documents, additional field codes control how those documents are handled. Several field codes are shared between standard form submissions and those associated with document scans, but some form fields are specific to each:

Email Field Codes (apply to both standard form messages and form messages with document scans):

Email Field Code (applies only to form messages with document scans):

• EmailSubjectOverride - Optional - Additional override subject that documents have over EmailSubject

Document Processing Field Codes (applies only to form messages with document scans):

• TableHeader - Optional - Overrides the header text of the generated field summary table used in the document's email body, summary PDF, and summary TIFF
• PageFileName - Optional - Overrides the file name template applied to every generated output file for the document.
• FilePath - Optional - Forces the local or network configured file export document processor to save to an alternate directory
• ExportSummary - Optional - Generates a summary of the submitted form fields alongside the document images. Field names also accepted: ExportPdf, IncludeExportSummary, IncludeExportPdf
• ConvertToPDF - Optional - Converts the document's image files to PDF. Field names also accepted: ConvertPdf, ToPdf, CONVERT-TO-PDF
• ConvertToTiff - Optional - Converts the document's image files to TIFF. Field names also accepted: ConvertTiff, ToTiff, CONVERT-TO-TIFF
• SkipCombineDocuments - Optional - Prevents multiple page images from being combined into a single file (if enabled). Field names also accepted: SKIP-COMBINE-DOCUMENT, SkipCombine, SkipCombineDocument
• SkipFileExport - Optional - Skips the local or network configured file export processor (if enabled) for this document
• SkipDocumentEmail - Optional - Skips the document email processor (if enabled) for this document
• SkipFileUpload - Optional - Skips the Azure File Share upload processor (if enabled) for this document
• SkipEbeFormatting - Optional - Skips EBE export and formatting (if enabled) for this document

The following is an example of how some of the above fields would be configured on a form for customization. All specific form fields listed above should be a field type of “Text”:

 
There are also some additional properties that come from the appsettings.json file that are the “default” if a value is not provided in the form. Examples of this would be:

• UseSendGrid – Determines if SendGrid should be used to send the email
• FromAddressEmail – The email address that the emails will be sent from
• FromAddressName – The name that will display as the contact that you receive the email from.
• DefaultMailTo – If no “EmailTo” is provided on the form and it should still be emailed it will send to this email by default.
• OverrideMailTo – If there was an “EmailTo” field that was provided on the form, but the OverrideMailTo setting was set, it will overwrite the existing EmailTo field.
• AllowPdfConversion – Determines if the document should be allowed to be converted to a PDF
• AllowSummaryPdf – Determines if the document should be allowed to include PDF form summaries
• AllowSummaryTiff – Determines if the document should be allowed to include TIFF form summaries

For more information regarding emailing forms, please review the following documentation on Drive Axle - Emailing Form Data Through Drive Axle. 

Form Custom HTML 

We use the ELEOS.usp_GetCustomHTML procedure to pull custom HTML specific to a FormCode from the database and build that into the HTML generated by a form email. We take this custom HTML returned from the database and append it to the HTML created from the form definition. This all gets combined into the email to be sent. This allows for customization of form emails, such as adding more information that is not on the form definition in Eleos or creating a custom button that takes you to a separate page. For this to work as expected, you need to return the custom HTML to be added to the form from the ELEOS.usp_GetCustomHTML procedure. You can add custom HTML specific to a form code in this procedure if you are checking the @p_FormCode parameter so that it matches the form code from Eleos.

Display Form To Driver

“Display Form to Driver” is an option only on “New Message” type actions for associated forms that allows for drivers to complete an action with or without the need of opening and launching the form within the application. When specifically disabled, this allows for a single click of an action that then also submits the form automatically. This can be useful when all form fields are prefilled on a form that also requires no user input to any fields.

A current use of this feature is to utilize them with the Action Requests feature, allowing us to request a mandatory action from a driver that they must acknowledge but when configured with “Display Form to Driver” as false the driver must acknowledge the action request but does not get further interrupted of changing screens and needing to manually enter value and complete the form.

For more information on the Action Request feature this can be utilized with, please review the following documentation Eleos - How To Use The Action Request Feature.