HotMailBoxes – “Add to elements based on barcodes in attachments”

Applies to version: 8.1.x and above, author: Martyna Kubiak

Functionality description

With WEBCON BPS users can now create HotMailBoxes. A HotMailBox automatically starts workflows or adds files to them whenever an e-mail message is delivered to an inbox configured in it. A HotMailBox can operate in one of the following modes:

• “Start one workflow for each e-mail”
• “Start one workflow for each selected attachment”
• “Add to elements based on barcodes in attachments”
• “Add to elements based on e-mail content”

Example – “Add to elements based on barcodes in attachments”

A workflow named “Agreement” is created where a .pdf document containing an agreement is generated. The document includes a barcode of a workflow instance in which it was created. Once a client sends an e-mail containing such an agreement, its scan along with client’s signatures is added to a workflow instance of such an agreement. Each .pdf attachment appended to an e-mail is searched for a workflow instance barcode. If it is found, the system reads the agreement document ID in the workflow and adds an attachment to it.

The “Agreement” workflow diagram is presented below

Fig. 1. The “Agreement” workflow diagram

• Registration – an initial step in an “Agreement” workflow. A registrant fills out all the required fields and uses the “Register” path to move to the step where an agreement file is generated with the data they entered in the form fields.
• Generating an agreement – a step containing the “Generate the PDF file” action triggered with a menu button. A template used for generating the agreement file contains a barcode with an ID of an “Agreement” workflow document the “Generate a PDF file” action applies to. A task holder in this step creates a .pdf file with an agreement, sends it attached to an e-mail to a client, and transits on the “Sent to client” path.
• Archive – a final positive step. Files containing scanned agreements sent back by the client are added to workflow documents.
• Canceled – a final negative step.

HotMailBox configuration

To start configuration, first create a HotMailBox. To do that go to “System settings” module in WEBCON BPS Designer Studio and click the “HotMailBoxes” item in the selection tree on the left. A “New HotMailBox” button appears in the upper bar – click it to start configuring new HotMailBox.

Fig. 2. Creating new HotMailBox

The “General” tab

There are five fields to fill out in the “General” tab of a new HotMailBox:

• “Hotmailbox” – enter the HotMailBox name here, as well as the server used for its operation. Filling out the “Description” field is optional. To activate the HotMailBox check the “Active” checkbox.
• “Connection settings” – the section is used to fill out parameters for connection with the mailbox. After selecting the “Use custom inbox settings” choose the server type and enter its address. Then, enter the data of a user whose account is to be used for connecting with a mailbox. When configuring connection with a mailbox, you can test the status of connection with the mailbox with the tool “Test connection parameters”.

Fig. 3. The “Test connection parameters” tool window

• “Folder settings (exchange)” – here, you can specify the mailbox folder from which the system downloads messages (“Source directory”) and to which it moves e-mails processed successfully (“Archive directory”) and unsuccessfully (“Error directory”). These folders must be created beforehand in the mailbox, and selected from the selection tree that appears after pressing the ellipsis button placed next to the source and archive folder fields.
• “Working mode” – for the purpose of this example select the “Add to elements based on barcodes in attachments” option in the “Main mode” field. Proceed to the “Attachments to be processed” field and choose which files are to be added to the workflow. Define how the names of those files are to be formatted in the “Template for created attachment name” field. Possible variants for a name template can be viewed in the context-sensitive help.

Fig. 4. Context-sensitive help for the “Template for created attachment name” field

In the described case, only the .pdf files containing signed agreement scan are searched for, so select the “Only PDF files” option in “Attachments to be processed”. Additionally, this section allows users to define operation executed on delivery of an e-mail containing a .pdf attachment with a code or with an incorrect code.

• “Additional attachments” – define additional files to be added to the started workflow. Here, you can append e-mail content to the workflow as an “.eml” file. It is also possible to define a template specifying which files are additionally downloaded. The available variables can be previewed in the context-sensitive help.

Fig. 5. Context-sensitive help for the “Additional attachments filter” field

There are no additional files downloaded in the discussed example.

Fig. 6. A demonstrative configuration of the “General” tab

The “Advanced settings” tab

Once you configure the “General” tab proceed to the “Advanced settings” tab. The tab is divided into two sections:

• “Restriction of supported e-mail sender list” – the field allows you to specify that only e-mails from senders defined in the data source are processed.
• “Limits of processed e-mails” – define the maximum number of e-mails processed within a day and a single iteration, as well as the number of days back from which the messages are downloaded.

An example of configuration of “Advanced settings” tab is presented in fig. 7.

Fig. 7. A demonstrative configuration of the “Advanced settings” tab

The “Barcode settings” tab

The “Barcode settings” tab consists of three sections:

• “General – the section allows users to specify the elements in the barcode the system searches for. As the barcode added to the template has a standard value in the discussed example, select the “Standard barcodes” option.
• “Barcode search algorithm” – adapt the way in which the system searches for barcodes to limit the percentage of unrecognized barcodes as much as possible. You can define the number of attempts (maximum three) undertaken before rejecting the barcode and the mode in which the system operates in each of them. The searching options available in the field: “None”, “Standard”, “Sharp”, “Sharp picture”, “Dilate”, “Large quiet zone size”, “Treat as picture”. You can also specify the sequence in which barcodes are read in a file (if there are more of them and they are of different types) and the input resolution of the scanned files. Once you set up all the parameters, you can test the configuration by clicking the “Verify configuration” button and selecting either basic or full test.

Fig. 8. A demonstrative configuration of the “Barcode settings” tab

The “Adding attachment settings” tab

The “Adding attachment settings” tab is divided into two sections:

• “Creating elements for unrecognized files” – the field allows users to define which document, in which workflow and process, and for which company is started if the system fails to find a correct barcode in the .pdf file. In the discussed example it is the “Agreement” workflow document. You also need to select a path the uses to register the document.
• “Additional form field values” – here you can assign e-mail data to respective workflow form fields, e.g. e-mail sender or title. Full list of available variables can be found in the context-sensitive help (fig. 9).

Fig. 9. Context-sensitive help for the “Workflow field values” field

The tab configuration for the discussed example is presented in fig. 10.

Fig. 10. A demonstrative configuration of the “Adding attachment settings” tab

Saving a HotMailBox

After configuring tabs “General”, “Advanced settings”, “Barcode settings”, and “Adding attachment settings” you can save your HotMailBox by clicking the “Save” button in the upper bar.

When correctly saved, a message appears with information on actions to be taken to make the changes in the HotMailBox effective.

Service configuration

After saving the HotMailBox, enable the “E-mail/MailApproval inbox monitoring” role in a service. To do that click the “System settings” button in the right, lower corner, select the “Services configuration” node from the selection tree on the left, choose the “Services” item, and select the right service.

Fig. 11. Service selection

Once you select a service, check the “E-mail/MailApproval inbox monitoring” role, and save changes in service configuration. For the HotMailBox to work correctly, you need to reload service configuration.

After clicking the “Load configuration” button, the system asks to confirm the intent to reload configuration, as this involves stopping all active service tasks. Stopped operations are restarted when a service reloads its configuration.

Fig. 12. Service configuration

Your HotMailBox is correctly configured. When an e-mail is received in a selected folder, the system checks if it includes any .pdf attachment. Each .pdf file is then searched for barcodes with document ID. If the system finds a barcode, the file is added as an attachment to the “Agreement” workflow.