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.  

 

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 form 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: 

  • FormsManageTrailer – Determines whether forms manage trailers (true or false) 
  • CurrentTrailerFormKey – The form field code that corresponds to the trailer to be attached
     

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 contain the CurrentTrailerFormKey, with a number attached to it. For example, “TRAILER-NUMBER1” and “TRAILER-NUMBER2” will be pulled if the field name matched the first part of the code. 

 

Form Validation 

When a form is submitted with a property of “server_validation_request” set to true, we use Server-Side Validation to ensure that the properties of the form are set to what we expect they should be. This server-side validation calls the ELEOS.usp_ValidateMessage procedure, which is used to return any issues with the form.  


If the ValidateMessage procedure returns results that correspond to a field code on the form, the validation request will fail and alert the driver that there are issues with the form that was submitted.  

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

 
Graphical user interface, text, application, email Description automatically generated 
 

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 API. The goal is to return true or false for a field name, which determines if the field should be visible. 

 

 

Form Emailing  

When configured, we can convert a form submission into an email with customizable fields. We can do things like dynamically set the EmailTo, EmailCC, EmailBCC, the subject of the email, and more. We interact with the following field codes on forms to configure emails: 

  • EmailTo - Required – The recipient of the email 
  • EmailCc – Optional – The email address to receive a carbon copy 
  • EmailBcc – Optional – The email address to receive a blind carbon copy 
  • EmailSubject - Optional - Overrides Default Subject line. 
  • TableHeader - Optional - Useful for formatting the body of the email. 
  • PageFileName - Optional - Useful for controlling Attachment name. 
  • FilePath - Optional - Can force save to alternate location. 
  • ConvertToPDF – Optional – Determines if the specific document form should be converted to a PDF 
  • ConvertToTiff – Optional – Determines if the specific document form should be converted to a Tiff 

The following is an example of fields on a form that is using the required EmailTo property, and a custom email subject. 

Example of form fields related to email on a form 

 
All of these fields can come from the form itself and are used to configure customization on a per-form basis. There are 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
     

 


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


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. 


Show Form Editor 

Show Form Editor is a property on an action linked to the form that allows for drivers to complete an action without the form opening in the application. This allows for single clicks of actions that will prefill information on the form and automatically submit it via a message.  


A current use of this show_form_editor property is Action Requests, allowing us to request an action from a driver, without the driver needing to open the form an enter values. For this functionality to occur, we need to use the API to add this show_form_editor property to the action linked to the form and set the value to "false". If the show_form_editor property is set to "true", it means that it will show the form and allow the driver to edit. 

Below is an example of a definition property on an action that includes the “show_form_editor” property.