ASR Solutions

Overview

Within this manual we will cover the features that the standard ASR designed Eleos Integration Document Poller provides. The Document Poller is a collection of background services embedded within your deployed integration. When enabled, the Document Poller downloads and processes documents, at a configured interval, that have been scanned through your Eleos mobile device application. As drivers scan and upload documents, the Document Poller ensures documents are downloaded, processed, converted, emailed, and/or forwarded as needed based on how the Document Poller settings are customized to meet your needs.

Getting Started

In this section we’ll review where the Document Poller settings are configured, and some of the basic settings for enabling or disabling the Document Poller and configuring how often documents are downloaded and processed.

The Document Poller settings are configured in your application settings (appsettings) file. To find your applications settings file, first you’ll want to navigate to the directory containing the integration. In most cases, this is found within the following directory C:\Eleos Integration\Active, but this may differ slightly depending on how your integration was installed. Once there, you will need to open the file “appsettings.json”.

Please note after making any updates to this file, you will need to recycle your application. More information on recycling your application can be found within the Appendix of this document.

Typically, the Document Poller is enabled by default. Enabling or Disabling the Document Poller can be controlled under the “Documents” section of settings. The “DownloadEnabled” setting controls the start of the Document Poller process, and when it is set to false, will prevent the integration from downloading scanned documents. The additional “ProcessingEnabled” setting controls the next part of the Document Poller for calling the various processing methods and when set to false will prevent documents from being processed. To disable the Document Poller, it is recommended to set both settings “DownloadEnabled” and “ProcessingEnabled” to false.

When these settings are enabled, they should also be configured to run each at their own interval. When the “DownloadEnabled” setting is set to true, the subsequent "DownloadIntervalSeconds" setting should be set to a value greater than 3. This configures how often documents will be downloaded from Eleos. Likewise, when the “ProcessingEnabled” setting is set to true, the “ProcessingIntervalSeconds” setting should also be set to a value greater than 3. This configures the frequency for how often documents are processed.

By default, your integration should also be set up to poll for documents within your respective Eleos Drive Axle platform. Within the “Settings” section of your appsettings file, the “DivisionCode” is your Eleos environment name, and the “EleosApiKey” is the registered Platform API key. Both are needed to ensure your integration is connected to the proper Eleos Drive Axle platform. This API key can be partially seen in the “Service Configuration” section within the Eleos Drive Axle Platform.

Main Processing Options

The processing aspect of the Document Poller works by configuring individual processing methods to handle documents for your specific needs, these are also configured within your appsettings file underneath the “Documents” section of settings for each of the different methods. Each method has its own purposes and individual settings but note multiple methods can be enabled at once to do more complex document handling (i.e., saving documents to a file location and emailing them to an address).  The following sections explain each method for processing: File Settings, Email Settings, Box Settings, Azure File Share Settings, and EBE Settings.

File Settings

Clients who use a directory on an imaging server or clients who require an imaging import process that scans a specific folder for new document deposits will want to take advantage of this method. The File Settings document processing method allows you to dictate where your documents are exported to on your system. Using this method without the network specific settings listed below requires proper read and write permissions for integration to access the directory. If more restrictive access is used and the application cannot be given direct access to the directory, a specified user with required permissions can be set up and configured via the network specific settings. Below are some of the notable settings specific for customizing the file processing functionality.

• SaveToFileEnabled: This is the first setting required to enable downloaded documents from the Eleos Drive Axle Platform to be exported to a file location. Setting this to true allows file processing to occur but configuring the file path (and potentially the network credentials) is still needed.
• FilePath: This setting is the file path and directory location that documents should be exported to by default, however, note that if the document fields function in your SQL scripting has a configured "FilePath" (see below sections for more detail), we will use this file path as an override first. When updating the directory path, backslash characters will require a second backslash for the application to register the path properly (i.e., "C:\\Users\\ASR\\Desktop\\Doc Testing").
• NetworkUsername: This is the username of the configured account that has the permissions to read and write to the directory and is needed if the application itself cannot be given direct access.
• NetworkPassword: This is the password of the configured account that has the permissions to read and write to the directory and is needed if the application itself cannot be given direct access.

Email Settings

Many clients prefer to have their documents emailed to a specific imaging import email address. This allows their imaging software to automatically check the inbox for new emails. When an email is received, using the subject and other properties on the email, the attachments (Scanned Documents) will be extracted and imported into their system for review. Below are some of the notable settings specific for customizing the document emailing functionality.

• DocumentEmailEnabled: This is the first required setting to begin emailing documents downloaded from the Eleos Drive Axle Platform. Setting this to true makes emailing possible, but more setup is typically still needed for configuring where these should be sent to by default.
• FallbackEmailTo: This is the email address that documents should be sent to by default, however, note that if the “OverrideMailTo” address (under the “Email” section within appsettings) is configured, it will use this address first. Likewise, if an “OverrideMailTo” address is not configured but the document scan has an “EmailTo” on the form it was scanned from (see below sections for more detail), it will use this “EmailTo” address first. If both are not configured, the email address listed in this setting will be used instead.
• Subject: This value has the default subject to be used during emailing. Using tokens containing a property name surrounded by “{ }” will automatically be replaced with the corresponding value during processing. If the document fields function in your SQL scripting has a configured “EmailSubjectOverride” (see below sections for more detail), we will use this subject first. Likewise, if an “EmailSubjectOverride” is not configured in your SQL scripting but the form the document was scanned from has an “EmailSubject” (see below sections for more detail), we will use this “EmailSubject” first. If both are not configured, the email subject listed in this setting will be used instead.
• CombineBatchEmail: This setting when set to true determines if documents that are processed in batches should be combined into a single email, when set to false batched documents are emailed separately as they are processed per batch (see below section for more detail).
  • BatchEmailSubject: This setting configures a specific email subject that will be used when the “CombineBatchEmail” setting is enabled.
  •  BatchEmailTo: This setting configures the specific email recipients that will be used when the “CombineBatchEmail” setting is enabled.
• FileNameTemplate: This setting configures a template for the name of a file that is sent by email.  Using tokens containing a property name surrounded by “{ }” will automatically be replaced with the corresponding value during processing. Note that {FileExtension} must be included at the end of the template.  Otherwise, the file name won't have an extension, and indexing software will not be able to open it.

Box Settings

Clients that use the Box cloud storage service as their image storing location can use the specific Box document processing method. To take advantage of this processing method, clients must be able to provide all Box specific credentials for the integration to point to the right Box service and location. Below are some of the notable settings specific for enabling the Box upload functionality.

• UploadToBoxEnabled: This is the setting required to enable downloaded documents from the Eleos Drive Axle Platform to be uploaded to your Box service and folder. Setting this to true along with configuring all other settings listed below is required for Box processing to occur.
• TargetBoxFolder: This is the folder path within your Box service that document scans will be uploaded to. When updating the folder path, backslash characters will require a second backslash for the application to register the path properly.
• ClientId, ClientSecret, PublicKeyId, PrivateKey, Passphrase, & EnterpriseId: These are all the specific credentials required to make a successful connection to your unique Box cloud storage for upload. These values should be filled out referencing your account settings and credentials information.

Azure FileShare Settings

Clients that make use of Azure FileShare can use the specific Azure FileShare document processing method. Like other cloud-based services, images can be uploaded to a storage location within Azure. To take advantage of this processing method, clients must also be able to configure their Azure FileShare connection string. Below are some of the notable settings specific for enabling the Azure FileShare functionality.

• UploadToAzureEnabled & AzureDocumentProcessorEnabled: These are both the settings used for enabling downloaded documents to be uploaded to your Azure FileShare. Setting both to true along with configuring the document share location and connection string is required for Azure FileShare processing to occur.
• DocumentShareName: This is the share location within your connected Azure FileShare that document scans will be uploaded to.
• AzureFiles: This last setting is not found within the same “AzureFileShareSettings” section but is instead configured under the “ConnectionStrings” section in appsettings. This setting is required for pointing to your specific Azure FileShare and to set up the connection during the uploading process.

EBE Settings

The last document processing method that is currently supported is exporting documents to EBE. Exporting documents to this software requires more unique settings and configuration (such as ensuring necessary store procedures are in place). The EBE processing method can kick off subsequent exports to other previously mentioned methods such as Azure FileShare and File directory. Below are some of the notable settings specific for enabling the EBE functionality.

• EbeExportEnabled: This is the setting required to enable EBE. Setting this to true along with configuring and setting up the stored procedures (these may require other database configuration) is required for EBE export processing to occur.
• DocumentIdxProcedure & DocumentXmlProcedure: These settings are used to reference the stored procedure names that are required to be setup within your database and are used for getting the metadata on the document scans.
• EbeExportToAzure: This is the setting used to enable the subsequent export to an Azure FileShare location and will do so using the same settings discussed above (under “Azure FileShare Settings”).
• EbeExportToFile: This is the setting used to enable the subsequent export to a File directory location and will do so using the same settings above, however, a specific path for EBE must be specified in the following EBE file export path.
• EbeNetworkFileExportPath: This is the specific path for EBE exported files and is required if the above setting is also enabled.

Common Settings Among Processing Options

While the currently supported processing methods listed above each detail their own specific settings, most of them have common settings that function the same across all document processing methods. Below highlights these common settings that are configurable on each method (The exception being the EBE setting).

• FileNameTemplate: This is the setting that controls the filename that the document file will be labeled with. The template uses a document property surrounded by “{ }” to automatically replace the value dynamically during processing.
• CombinePages: This setting, when enabled, will combine the pages of a document scan when multipage.  CombinePages is also the top-level setting that is required to be enabled when CombineSummaryWithPages is enabled, even if a driver is doing single page scans.
• CombineSummaryWithPages: When the “Documents” level setting for allowing summary PDF’s and/or summary Tiff’s is enabled (“AllowSummaryPdf” & “AllowSummaryTiff”), and this “CombineSummaryWithPages” setting is also enabled, it will combine those other summaries with the document scans. CombinePages must be enabled as well so that CombineSummaryWithPages will function as expected.
• ArchiveBatches: This setting, when enabled, will zip all batch files into a single archive. When used, it is recommended that the “Document” level setting for batching (“BatchingEnabled”) is also enabled.
• BatchArchiveName: This setting is to be used when the “ArchiveBatches” setting is also enabled and will configure the specific zip archive file name to use when batched document scans are processed. When used, it is also recommended that the “Document” level setting for batching (“BatchingEnabled”) is also enabled.

Additional Customizations

Eleos.udf_DocumentFields Scripting Changes

The SQL function, ELEOS.udf_DocumentFields within your TMS database handles returning custom properties to be used during document processing along with the properties sent on the meta data form itself. The meta data form being the Eleos Drive Axle Platform Form that is linked to the document scan. The original document properties are contained within the form itself. The function allows for more or supplementary fields to be used as well. For all the custom changes discussed in this section, at the very least, the new field needs to be added to the “Fields” table definition and a result must be “Selected” into this column for the value to be returned.

• [EmailTo]: By setting and returning the EmailTo column from the function, you can specify emails based on determinate logic within. This email will override the default appsettings email address.
• [EmailSubjectOverride]: By setting and returning the EmailSubjectOverride column from the function, you can specify a specific subject, including property values surrounded by { } characters for replacement. This subject will override the default appsettings subject.
• [PageFileName]: By setting and returning the PageFileName column from the function, you can specify the exported file name based on determining logic within. This filename can include property names surrounded by { } for replacement.
• [FilePath]: By setting and returning the FilePath column from the function you can override and control the exported document directory based on determinate logic. This export path does not require providing other ‘\’ characters like the settings file FilePath property required. For example: "C:\Users\ASR\Desktop\Doc Testing".
• [SkipDocumentEmail]: By editing udf_DocumentFields to return a value for this SkipDocumentFields property, you can either allow or disallow documents to be emailed by adding a “CASE WHEN” in the function. This will only determine when a document should be emailed if the “EmailDocuments” setting in Appsettings section is enabled. Possible Values for [SkipDocumentEmail] are: 1, on, yes, true. For example, [SkipDocumentEmail] = ‘true’
• [SkipFileExport]: This setting prevents files from being exported to their designated location. Like the above setting, it could be helpful to add a “CASE WHEN” to alter when a document should be processed. This will only determine when a file should be exported if the “SaveToFile” setting in Appsettings is enabled. Possible Values for [SkipFileExport] are: 1, on, yes, true. For example, [SkipFileExport] = ‘true’

Eleos Drive axle Scan Form & Action Updates

The Document Poller also supports the ability to control some of the settings and default values already discussed as well as additional features based on the Eleos Drive Axle Form definition, by making use of the form field codes. In the form editor, when adding a new field, each field has a “Code” property. This is the unique identifier within the form for the value contained within that field. Additionally, this field value can be pre-populated with a set value or token replacement value ({DriverId}) within the scanning action linked to that specific form.

Emailed Documents

• EmailTo: Adding a text field to your form with a field code of “EmailTo” ensures that your document will be emailed to the address listed on the form. Whether listed as a static email address or a token that will link via property name to a column returned from Eleos.udf_DocumentFields.
• EmailSubject: This field works the same as the EmailTo field described above. The only difference is the defining Field Code. To override the default email subject from settings, you will need to set the value of a field called “EmailSubject”.
• SkipDocumentEmail: By adding a text field to your form with a field code of “SkipDocumentEmail”, you can change which forms should be emailed when scanned. Prefilling this text field with the value “true” or “on” will prevent the form from being emailed during processing exported only if the “EmailDocuments” setting in Appsettings is set to true.

Exported Documents

• SkipFileExport: This overrides functionality by adding a text field to your form with a field code of “SkipFileExport” and prefilling the value with “true” or “on”. This prevents the document that is scanned from being exported. Not including this property on the form, or having it set to a different value such as “false”, will allow the document to be exported, only if the “SaveToFile” setting Appsettings is set to true.

For more details on how to update Forms, Actions, and emailing scans through the Eleos Platform, please see our extensive Knowledge Base article on this process: Drive Axle - Emailing Form Data Through Drive Axle.

Form Summaries

A form summary is an automatically generated representation of the exact Eleos Drive Axle Form the driver completed and sent along with their scanned documents. This form holds all the meta data included within the document. Based on other configuration values available, this document can be emailed within the body with the attached documents, attached as a PDF or TIFF, exported as a PDF or TIFF, and even combined with your driver’s document scans within a single PDF or TIFF. When combined, this single file contains all scans and the form summary in one document. An example can be seen within the Appendix.

• To begin receiving the Form Summary, you must enable the feature within appsettings.json, under the “Documents” subsection with the “AllowSummaryPdf” setting for PDF summaries or the “AllowSummaryTiff” setting for TIFF summaries. Using the value true will enable the feature and false will disable the feature.
• By default, enabling the feature will only include the Form Summary within the body of sent document emails.
• To export the Form Summary as either a PDF or TIFF to the document directory, a form field with one of the “Field Codes” below will allow conditional checks for attachment. To pass the conditions, you must prepopulate the Form Field within the corresponding Action with one of the “Values” below. Also note that for exporting to PDF to occur successfully, all documents should be only converted to PDF file types and later for exporting to TIFF to occur successfully, all documents should be only converted to TIFF file types.
  • Possible Field Codes: ExportSummary, ExportPdf, IncludeExportSummary, IncludeExportPdf.
  • Possible Values: 1, on, yes, true.

Converting Documents to PDF

Documents can also be set up to automatically convert into a PDF if that is your preferred method of storage. This functionality can convert both black and white document scans and color photo scans.

• To convert documents to PDFs, you must first enable the feature within appsettings.json under the “Documents” subsection with the “AllowPdfConversion” setting. Using the value true will enable the feature and false will disable the feature.
• To trigger the conversion of a document to a PDF, a form field with one of the “Field Codes” below will allow conditional checks for attachment. To pass the conditions, you must prepopulate the Form Field within the corresponding Action with one of the “Values” below.
  1. Possible Field Codes: CONVERT-TO-PDF, ConvertToPdf, ConvertPdf, ToPdf.
  2. Possible Values: 1, on, yes, true.

Converting Documents to Tiff

Like the above conversion, documents can also be setup to automatically convert into a TIFF if that is instead your preferred method of storage. This functionality can convert both black and white document scans and color photo scans.

• To trigger the conversion of a document to a TIFF, a form field with one of the “Field Codes” below will allow conditional checks for attachment. To pass the conditions, you must prepopulate the Form Field within the corresponding Action with one of the “Values” below.
  1. "CONVERT-TO-TIFF", "ConvertToTiff", "ConvertTiff", "ToTiff"
  2. Possible Values: 1, on, yes, true.

Application Settings – Additional Settings

Combining Multi Page Document Scans

The ability to combine pages is an added feature within the integration that aids with merging the number of scans per load. If a driver scans a multi-page Bill of Lading with Batch Scanning enabled, a single document batch could have two, three, six or more scans. When the “CombinePages” setting is enabled, you can combine all those documents into a single document and when desired, include a summary (as mentioned in the above section) as well. The configuration for this feature is controlled per processing method within the appsettings.json file found within your installation directory under the “Documents” section and then for each processing method section of settings. Each processing method will have this listed as their own “CombinePages” and “CombineSummaryWithPages” settings.  Note that in order to enable “CombineSummaryWithPages”  so a summary is included, the “CombinePages” setting is required to be enabled, even if the driver only scans a single document. When multiple documents are scanned, they would have to be combined into a single document batch for a summary to be included.  

Poll Documents from Multiple Eleos Driveaxle Environments

While this feature is not typically recommended by ASR, there are a few client exceptions. In those cases, a client may have multiple Eleos Drive Axle Environments for different divisions within their company. In some cases, multiple integrations are proper. In others, a single integration is designed to support multiple environments. In these cases, a client may want to poll for documents from a single poller in multiple locations. There is a section within appsettings, under the “Documents” section called “AdditionalDivisionsToPoll”.

By default, this setting will be configured blank. You will see under the heading “” : “” (two sets of empty quotes separated by a colon). To poll a second and even third or more divisions, the values within each set of quotes will need to be updated.

• Left Side Quotes: This side is reserved for the division name. This can be found within the keys of the usage graph within the Eleos Drive Axle Platform. On the right side of the usage graph, the environment displayed will be labeled. These values are typically lowercase and related to the company name in some way.
  1. Example: “asr” and “asr-dev”.
• Right Side Quotes: The right side is reserved for the Eleos Drive Axle Platform’s API Key. This allows the document poller to make a connection with the platform to process documents. You API key can be found under in the platform by navigating to Home -> App Configuration -> Service Config and scrolling to the bottom of the page. If your key is hidden with **** characters, a new key can be generated.
  1. Example: “asdlf;kajsfjowieufpois2k1j0asdlj1-asf0sadflj1”.
• Full Example: Based on the information provided for the “Left” and “Right” sides, when complete, you should have a setting that looks like this.
  1. “asr”: “asdlf;kajsfjowieufpois2k1j0asdlj1-asf0sadflj1”.

Drive Axle – Additional Settings

Remove “Add Page” Button on Scans

In Drive Axle, the number of pages for a document type(s) can be limited so that drivers are not able to use the “Add Page” button during the scanning process to scan multiple pages of one document type. 

Limiting the number of pages for a document type to “1” will make it so that drivers do not have to option to upload more than one scan page for that document.

To remove the “Add Page” button on scans, log into Drive Axle and go to the Eleos Platform, then go to App Configuration, and select “Document Types” from the drop-down menu.  Put “1” in the Page Limit column for the document type that should not have the “Add Page” option. 

For example, by inputting 1 as the page limit for documents with the BOL type, then the driver is only able to scan one page after they select the document type and will not see the “Add Page” button.  

Appendix

IIS - Restarting an Application Pool

1. Open IIS on your webserver.
2. On the left side, under “Connections”, click “Application Pools”.
3. Within the center, the “Application Pool” section should be opened and display all application pools configured within your IIS instance.
4. Restart your application pool using one of the methods explained below.
   1. Recycle - Right click on your Eleos application pool responsible for running the integration that you have recently updated. Within the displayed menu, select “Recycle”. This will stop and restart the application pool with a single click.
   2. Stop / Start – Right click on your Eleos application pool responsible for running the integration that you have recently updated. Within the displayed menu, select “Stop”. This may take a few seconds to fully stop as the background services need to finish their current execution. Once stopped, right click again on the same application pool, this time selecting “Start”. The integration should now be up and running again with the recent updates included.

Form Summary Feature

Below is a screenshot of the Form Summary feature discussed within this document.

• Orange Section: When this setting is enabled within appsettings.json and the Form has the Form’s corresponding unique “Form Code”, the generated summary will only be present within the email body.
• Yellow Section: When the setting is enabled, the Form has the Form’s corresponding unique “Form Code” and one of the field level flags are present, for example: “AttachSummaryPdf – True”, the generated summary will also be included as a PDF attachment.

Figure 1: Example Form Field additions.	Figure 2: Example Action updates to prepopulate the fields.