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, ELEOS.udf_DocumentFields, that we can pull from that isn't limited to what's contained in the metadata file. 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 udf_DocumentFields may look like:
This is using the same XML-pivot that our other functions use to return key/value pairs. If we wanted to add our own piece of data that we could format into exported documents, we would add a column to the @Fields table and name it with the Key we want, then ensure we insert the corresponding Value into that column. So, for example, in the state this is in now, we could put {ImagingDocType} into the file name template and expect it to be replaced appropriately in the extracted file names.
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.udf_DocumentFields. The Document Poller doesn't currently support the ability to change the template on a per-document basis. For example if we use a Tire Pressure Sheet scan, if FileNameTemplate = “{UserName}_{DocumentTypes}_{LoadNumber}_{Tractor}_{Trailer}”, the expected tire pressure sheet scans will come in as "TESTUSER_Tire Pressure Sheet__1234_5678_1.tif", noting that the load number is missing between the DocType and Tractor. And for an additional example, if both the tractor and trailer were missing for a BOL scan, it would come in as, "TESTUSER_BOL_1234567___1.tif". With the underscore “_” separating each value, the “___”, would indicate that there are 2 values missing from the FileNameTemplate.
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.
