ASR Solutions

Form Design

To set up a form to have its data emailed, it utilizes fields that are added (and hidden) to represent standard email information. Form data can be emailed with data that contains documents or with data that is simple messages. Each method of emailing form data requires certain fields and results in a slightly different email.

Document Forms

Emailing form data that includes documents requires the following: FormCode, EmailTo, Document/Photograph, and DocumentType. They should be added into the field section of the form to properly indicate the email information. The EmailSubject, EmailCc, and EmailBcc are optional fields. The following fields are case insensitive:

• FormCode (Required)- Used to reference the forms metadata.
• EmailTo (Required) - Used as the recipient on a standard email.
• Document/Photograph (Required) – Needed to initiate the scan mode.
• DocumentType (Required) – Needed to indicate type of document being sent through. (Type Photograph used in screenshot)
• EmailSubject (Optional) - Used as the subject on a standard email.
• EmailCc (Optional) - Standard email Cc value.
• EmailBcc (Optional) - Standard email Bcc value.

**Some clients running the older integration model prior to Fall/Winter 2023 enhancements will have Case Sensitive form codes and will require PascalCase to work properly – i.e. EmailTo not EMAILTO**

The document form example also includes the additional Document/Photograph field that only needs to be set to type Scan Mode. The document form example also includes the type of documents that can be scanned such as a Photograph indicated by setting the field to type Document Type.*

Additionally, you can choose to include or exclude summary PDFs in document scans. This is also controllable through another optional field on the document form but also requires settings to be toggled in the appsettings.json file within your integration.

Under the “Documents” section within the appsettings.json file locate the setting titled “AllowSummaryPdf” and either set it to true or false for enabling or disabling the use of summary PDFs with document scans.

You’ll then have to enable the document processor for emailing which can be found under the “Documents” section then “EmailSettings” sub section within the appsettings.json file. Under this sub section the setting titled “DocumentEmailEnabled” should be set to true. Any additional document processors can also be enabled and further information on these processors can be found in our Eleos – Document Poller Manual 



When the necessary settings are set to true, you can then specify per document form if a PDF summary export should be included or not by adding a form field with a code of either "ExportSummary", "ExportPdf", or "IncludeExportSummary", "IncludeExportPdf".

This then needs to be prefilled with one of the following strings, “true”, “yes”, or “1”.

Message Forms

Value / Token Replacement

Once the form is created, the next steps involve linking the form to a component in Drive Axle such as an action, however, note this process also works with other components like menu items, and custom screens. Linking this form to an action we can then set the pre-filled field values. For all email information, the pre-filled values on an action should always be set as type “Other…” Note, this type does not need to be specified when setting pre-filled values on other components like menu items, and custom screens.

Note if the action is for a document related form, the required additional field FormCode should always be set to the code of the metadata form itself. For the example shown in the screenshot above, the FormCode shows this additional field if this was for a document related form where this would be prefilled to “A-TEST-FORM".

Adding Tokens

Replacement Locations

End Result

As you can see the result is our form has properly sent its data and subsequent attachments to the specified recipient with proper formatting working either via SendGrid or SMTP. Please note that within the email, form data is formatted within the body and if configured, a pdf copy of the formatted contents is provided as well.

Note: The photo attached is only contained in the email on document scanning forms. 

Update Or Remove Addresses In EmailTo

Emails may need to be added or removed from the EmailTo field for several reasons, but it is important to remove any email addresses that are no longer valid, because ASR will be notified if drivers completing a form that goes to an undeliverable email address.  (If the EmailTo field contains a token, that change will have to be made by your staff that has access to your TMS master data).  If your EmailTo is not dynamic, you can change the contact that the form is sent to by updating the form in Drive Axle. 

1. Locate the ‘Action’, ‘Menu item’, or ‘Custom Screen’ that the form is tied to.  
2. Remove invalid email address from EmailTo field.  Add another email address by typing it in the EmailTo field, and if multiple email addresses are added, be sure to separate them with a comma.
3. Review all your Drive Axle forms, menus, actions, and custom screens, and check the EmailTo values in each to make sure there are no old or invalid email addresses listed, in the case that the contact that was just removed is still associated with other forms.

Below is an example of a Pay Inquiry Menu item showing where to edit the EmailTo field as well as the form name associated with it.

Signatures

Electronic signatures captured on forms are another type of data that can be emailed through the Eleos platform. Emailing these signature captures requires the same “EmailTo” field mentioned under the “Message Forms” sections above. The other additional form field that is required is one with a “Signature” type. It should be noted too if a document scan is also needed, an inline document scan must be used which can be done by also including a “Form Scan” field.

Form fields for signatures should also be made visible as users will need to interact with this field to tap it and capture their drawn signature.

The above shows the necessary additional form field if a document scan is needed with a signature. This field, if added, should also be made visible as users will need to interact with this field to tap to scan documents.

Users can utilize either the “X” symbol for erasing the signature from the box or the “✔” symbol for confirming the signature they currently have. For a signature to be included in the form data users will need to click the “✔” symbol before sending the form. This can be enforced by making the signature form field “Required” in the Eleos Form Definition which will force the user to select the “✔” symbol on their signature before they can submit the form.

The above shows how the additional in line document scan is added if it is also needed on the form.

The resulting email that is sent contains the summary of fields on the forms along with the attached PDF that shows the signature the user drew.

Retrieving Signature Image Data From The Database

Since emailed signatures are only visible on emailed PDF’s and are not copiable like other emailed form data constructed in HTML, retrieving the raw image data of these signatures requires looking at the raw form field data from the database connected to the integration and converting it back to image data that can then be used as needed elsewhere.

When a form is submitted with a signature form field the ELEOS.MessageFields table in the database will contain the BASE64 data that represents the signature the user drew. You can query for the signature data if you know either the “Handle” of the form or the “DocumentId” if the form also contained an inline document scan.

To retrieve the signature data by the “Handle” of the form, you should first identify the message from the ELEOS.MessageHistory table that corresponds to the form submission that had the signature. You can look at the “FormCode” of the records in the ELEOS.MessageHistory table to determine if that is the same form code within Drive Axle that includes a signature form field.

In the above screenshot this record highlighted in blue is from the form submission shown in the previous three screenshots.

Once the “Handle” is identified from the ELEOS.MessageHistory table for the corresponding form sent in, you can use that in the following query to join to the ELEOS.MessageFields table and find the “FieldName” of the signature_url that corresponds to the signature form field name along with the “FieldValue” which is the raw signature data represented in BASE64.

SELECT   [Handle]                   = H.[Handle]
        ,[FieldName]                = F.[FieldName]
        ,[FieldValue]               = F.[FieldValue]
FROM    ELEOS.MessageHistory H
        LEFT JOIN ELEOS.MessageFields F
            ON  H.[MessageId] = F.[MessageId]
WHERE   H.[Handle] = 'your-handle-identified-from-message-history'
    AND F.[FieldName] LIKE '%.signature_url'

SELECT   [DocumentId]                 = H.[DocumentId]
        ,[Handle]                     = MF.[MessageId]
        ,[FieldName]                  = MS.[FieldName]
        ,[FieldValue]                 = MS.[FieldValue]
FROM    ELEOS.DocumentHistory H
        LEFT JOIN ELEOS.DocumentFields DF
            ON  H.[DocumentId] = DF.[DocumentId]
            AND DF.[FieldName] = 'FileName'
        LEFT JOIN ELEOS.MessageFields MF
            ON  MF.[FieldName] = 'DocumentId'
            AND DF.[FieldValue] = MF.[FieldValue]
            AND DF.[FieldChecksum] = MF.[FieldChecksum]
        LEFT JOIN ELEOS.MessageFields MS
            ON  MF.[MessageId] = MS.[MessageId]
            AND MS.[FieldName] LIKE '%.signature_url'
WHERE H.[DocumentId] = 'document-id-number-identified-from-document-history'