Overview
Modifying the template for file names or batch names that are saved can be controlled on a per processing basis. Each processor has its own section of settings within Appsettings.json which allows you to configure filenames differently based on what is processing it, as well as batch names if batches are enabled.
How the Filename Template Works
The FileNameTemplate is a value for naming files that are processed by the Document Poller to a local directory. Token replacement can be utilized when modifying the file name to dynamically name a file based on information about the file, user, and more. Below is an example of what the FileNameTemplate value may look like in your environment:
The values are using curly braces “{}” to represent values that need to be replaced in the file name, meaning that each piece of it is filled in dynamically from metadata on the document. The text inside of the curly braces “{}” is the key of a key/value pair of document metadata, representing the name of the property whose value should be filled into that spot. Most are straightforward, but a few have dot notation to access elements of an array (e.g., "DocumentTypes.0", meaning the first element of the DocumentTypes array) or properties on a sub-object (e.g., "Identifiers.LoadNumber"). Additionally, if you anticipate scenarios where a driver may scan multiple pages for a single document, you must include some way to differentiate those from one another. We typically use {PageNumber}, but in other cases clients have used a form of timestamp as well. The {FileExtension} token must be included at the end of the FileNameTemplate as well, so that files can be properly named and exported.
The tokens used in the FileNameTemplate match up to the metadata that we get from Eleos when we're retrieving documents from the API. Here is an example of the metadata file of a document:
Using the FileNameTemplate segments in the example from the beginning of this document, you can see that "DocumentTypes" is indeed an array, and its first (and only) element is the document type we want to put in the file name. There is an "Identifiers" property that has its own properties, i.e., a sub-object, and its "LoadNumber" property is the load number we fill in.
The document's metadata file is where most of the common metadata is sourced from, but there is another very important source of document data that we can pull from that isn’t limited to only what’s contained in the metadata file, this is the ELEOS.usp_DocumentFields_Custom procedure (note if this procedure is not found within your database, the ELEOS.udf_DocumentFields function is where you will want to look instead). Its job is to return key/value pairs that are combined with the documents existing metadata while it's being processed, effectively letting us insert our own metadata into the process. Here is an example of what this scripting may look like:
As shown above, if we wanted to add our own piece of data that we could use for formatting when exporting documents, we would insert into to the #DocumentFields table and name it with the Key we want, then ensure we insert the corresponding Value we want. So, for example, in the state this is in now, we could put {DRIVER-USERNAME} into the file name template and expect it to be replaced appropriately in the extracted file names. Additionally, we can also update existing values that are already inserted by default. Also shown above, if we wanted to update the value of the default value ImagingDocType we would just need to update the #DocumentFields table with the updated Value we wanted where our Key matches the name of the default value.
For more information on what values are already inserted by default into the #DocumentFields table see the default values section commented within the ELEOS.usp_DocumentFields_Custom_Template procedure (note as mentioned above if this procedure is not found within your database, the ELEOS.udf_DocumentFields function is where you will want to look instead).
If one of the tokens is not replaced with a value and is missing from the file name, then it could be because the metadata for the document does not contain that value, and it is not a value returned by ELEOS.usp_DocumentFields_Custom (or the ELEOS.udf_DocumentFields function if the custom procedure is not found). The Document Poller also allows the ability to change the template on a per-document basis by specifying on the form field of the associated document scan a code of "PageFileName" that when populated with a different template name will override the one in appsettings. If we have a Tire Pressure Sheet scan as an example, if FileNameTemplate is set in appsettings as “{UserName}_{DocumentTypes}_{LoadNumber}_{Tractor}_{Trailer}_{PageNumber}”, but we are missing the underlying SQL that populates the {LoadNumber} replacement value, the expected tire pressure sheet scans will come in as "TESTUSER_Tire Pressure Sheet_{LoadNumber}_1234_5678_1.tif", noting that the literal string {LoadNumber} was not replaced between the {DocumentTypes} and {Tractor} replacement values. Also, for this same example if when filling out this document scan, we specified on the form a value for the “PageFileName” field such as “{UserName}_{DocumentTypes}_{TeamLeader}_{Tractor}_{Trailer}_{PageNumber}” that individual scan for the tire pressure sheet would instead come in as "TESTUSER_Tire Pressure Sheet_TestLeader_1234_5678_1.tif"
Batching Overview
Batching is the process of handling multiple documents scanned for the same group at the same time, and a "BATCH-KEY" identifies a given batch, or group of documents so that they are kept together. Once a load is completed or once an hour has passed since the batch was created, the batch will be ready for processing within the integration. During processing, the batch can still have its contained documents converted, combined, etc. For more information on batches and batch settings, see our Eleos - Document Poller Manual, which includes batch settings that are specific to EBE since by default documents that are exported to EBE are always batched and archived for upload and indexing.
Regardless of your enabled processors, BatchingEnabled must be set “true” in Appsettings.Documents to allow any sort of batch processing to function. In the settings for each processing option, to support batches, there is ArchiveBatches and BatchArchiveName. If ArchiveBatches is set to “true”, then the batch archive will be named using the BatchArchiveName. ArchiveBatches is the Boolean value which determines if the batched documents should be compressed into a single zip archive when exporting, and BatchArchiveName is a string value which determines the zipped archive name. This setting supports token replacement like the other filename settings.
Settings for Each Processing Option
FileNameTemplate exists in the settings for each processing option, along with the ArchiveBatches and BatchArchiveName settings. The following sections detail what the settings are for and where the FileNameTemplate setting is located so that it can be modified.
FileNameTemplate is a string value for naming exported files through each of the processors individually. This setting supports token replacement and custom values. For example: {SDKUserId}_{Identifiers.LoadNumber}_{DocumentTypes.0}_{PageNumber}{FileExtension}
Appsettings.FileSettings
This section is specific to documents that are being exported by the Document Poller to some form of local directory or network share.
Appsettings.EmailSettings
This section is specific to documents that are being emailed by the Document Poller to an indexing inbox or storage email address.
Appsettings.BoxSettings
This section is specific to Box uploads where processed documents are then uploaded to Box.com for file storage.
Appsettings.AzureFileShareSettings
This section is specific to documents that are being uploaded to Azure's File Storage system.
