To download a PDF of this document, please see the attachment.
This document shows the ability to email form data through the Eleos platform. This feature allows you to send data such as an image through a form to an email utilizing standard emailing fields and formats. In our original integration code, ASR Solutions had to develop custom forms, PDF processes, or scanflows for clients that would want to include an image with form data emailed or sent to a location. ASR has since built default logic in our integrated document poller so that now a client can create their own forms in Drive Axle, allowing an image capture with the fields filled out on the form to go to an email with a formatted layout.
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.
- 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.
Additionally, you can choose to include or exclude summary PDFs in document scans. This is done through another optional field on the document form but also requires a setting 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.
When set to true, you then must include the additional document form field and call it “IncludeSummaryPdf”.
This then needs to be prefilled with one of the following strings, “true”, “yes”, or “1”.
Message Forms
Emailing form data that only includes messages requires just the following, EmailTo, it should be added into the field section of the form to properly indicate the email information. The EmailSubject, EmailCc, and EmailBcc are also optional fields.
EMAILTO (Required) - Used as the recipient on a standard email.
EMAILSUBJECT (Optional) - Used as the subject on a standard email.
EMAILCC (Optional) - Standard email Cc value.
EMAILBCC (Optional) - Standard email Bcc value.
Note that for the email information fields on both examples and the additional FormCode field on the document form example, we are setting the fields to type Text and specifying the Code in all uppercase. It is also recommended that these fields be set as non-visible so that they are not seen by drivers. 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.
Value / Token Replacement
Once the form is created, the next steps involve linking the form to either an action or menu item so that we can 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 a menu item.
The required field FormCode for the Document Form should always be set to the code of the metadata form itself. For the above action and menu item examples the FormCode for this Document Form is A-TEST-FORM.
Adding Tokens
Adding tokens for replacement will occur in multiple locations depending on the use case.
- Menu Item: For example, we add a testing form to our default menu.
- To update the tokens for those values, you’ll want to locate the menu the form was added to.
- Select the menu item that was added for the form.
- On the right side, you should now see all the fields on the form listed out.
- Select the item you want to replace, and edit your tokens, or static values.
- Actions: If you continue to extend this functionality, and you add a form corresponding to a load, stop, or even a dashboard item containing a button, the updates should occur within the Actions Menu.
- Create the action that you want to tie the form to.
- Select Message Type.
- Select the newly created form to tie the form to the action (button).
- You should now see all the form fields listed on the right-hand side in a similar fashion as on the Menu item.
- Select the item you want to replace and edit your tokens or static values.
Replacement Locations
Our prefilled field values are also where you would update the values for either Token Replacement or input static emails that you directly want to send out. There are a few ways that this can be done.
- ELEOS.udf_EmailCustom - This is currently where we have items such as TeamLeader, DriverName, DriverEmail, etc. being populated. As of right now within the function the only items that will return as usable replacement values are DriverId, DriverName, DriverEmail, MessageDate, and DriverManager.
- To use these items within your form values, a token replacement is required matching the field being returned. For example, the function returns the value [DriverId] in its SELECT. To use this in your subject simply add {DriverId}.
- Note: These items will not be replaced until we are generating the email, so the value stored in the database will remain as {DriverId}.
- Field Values on the Form - Any of the fields on the form can also be used as replacement values. To replace a value in the subject with a field value, we do the same as above using a code value.
- Custom Functions – These replacement values require two sets of curly braces, but they will update as the form is being filled out. Therefore, these items will show up in the database as the replaced value, and not {{item.custom.field}}.
- ELEOS.udf_StopCustom - Used to pull specific custom values based on a stop. This can be used for Actions designed in the platform on the stop level of the loadlist. Ex. {{stop.custom.StopId}}
- ELEOS.udf_TripCustom - Used to pull specific custom values based on the load. This can be used for Actions designed in the platform on the Load level of the loadlist. Ex. {{load.custom.MoveId}}
- ELEOS.udf_UserCustom - Used to pull specific values for the user. These values can be used anywhere within the application since they are stored on the user themselves, logged into the application. Ex. {{user.custom.DriverManager}}
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 with both SendGrid and SMTP. Please notice that within the email, all form data is formatted within the body and a pdf copy of the formatted contents is provided as well for future reference. 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.
- Locate the ‘Action’, ‘Menu item’, or ‘Custom Screen’ that the form is tied to.
- 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.
- 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.
