HotMailBoxes – Adding files to workflow instances based on barcodes

Applies to version 8.2.x and higher; Author: Martyna Krzyżak

Functionality description

WEBCON BPS Designer Studio allows us to create HotMailBoxes. Through the correct configuration of such a HotMailBox, it is possible to automatically launch workflows or add files based on received e-mail messages.

A HotMailBox has 4 operating modes:

  • Start one workflow per e-mail message.
  • Start one workflow per specified attachment.
  • Adding files to workflow instances based on barcodes in those files.
  • Adding files to workflow instances based on e-mail message contents.


Example: Adding files to workflow instances based on barcodes.

The organization uses a workflow called ‘Agreements’, which generates PDF documents containing the contract and a barcode linking to the workflow instance from which the file was generated. After sending such an agreement to the client via email, we want a scan of the signed document to be attached to the corresponding workflow instance. All PDF attachments in the e-mail should be searched for a barcode that links to a workflow instance. If a barcode is located, the system will read the ID of the workflow instance, and add the attachment to that instance.

The diagram of the proposed ‘Agreements’ workflow can be seen below (Fig. 1)

Fig. 1 – Agreements workflow diagram


  • Registration – This is the starting step, the person registering this workflow instance fills out all required fields and forwards it to the next step via the ‘Register’ path button.
  • Generate agreement – On this step, a ‘Generate PDF file’ action has been configured and added as a menu button. The template from which this file is created contains a barcode with the ID of the workflow instance from which the PDF file was generated. The user who is assigned to this step creates a PDF file with the agreement and sends it to the client via e-mail, they then click the ‘Sent to client’ path button.
  • Archive – Positive end step. Signed agreements sent back b clients will be attached to workflow instances residing in this step.
  • Canceled – Negative end step.


HotMailBox Configuration

Start by creating a new HotMailBox. In WEBCON BPS Designer Studio, go to the ‘System settings’ section, and find ‘HotMailBoxes’ on the tree on the left-hand side. After selecting ‘HotMailBoxes’, the ‘New’ button on the top bar will become available (Fig. 2), click it to begin configuring a new HotMailBox.


Fig. 2 – New HotMailBox


General tab

The ‘General’ tab of the HotMailBox configuration contains the following 5 sections:

  • “HotMailBox” – This section contains the HotMailBox name and server on which it will run. In order for it to work, the “Active” checkbox must be marked.
  • „Connection settings” – Used for defining connection parameters. Select Use custom inbox settings and choose the server version and address. Then enter the login credentials of the user through which the connection to the server will be established. The “Autodiscovery” tool (Fig. 3) may come in handy to detect a server address based on user credentials. “Test connection parameters” (Fig. 4) can be used to check the connection.


Fig. 3 – Autodiscovery tool


 Fig. 4 – Test connection parameters tool


  • ”Folder settings (exchange)” – Define the folder of the inbox from which the system will obtain messages (“Source directory”), the folder where correctly processed messages will be placed (“Archive directory”), and were incorrectly processed messages will be placed (“Error directory”).
    First, create a folder in your inbox, and then find them on the choice tree by clicking “Change”.
  • “Working Mode” – For this example, in “Main mode” select “Join element by barcode found in attachment”, then under “Attachments to be processed” choose the method for selecting which attachments will be added to the workflow, and under “Template for created attachment name” define what these attachments will be named. Click the contextual help (“i”) button to learn about possible configurations for the attachment name template (Fig. 5).

 Fig. 5 – Attachment name template contextual help


In this example, only PDF files with signed agreements will be processed. So the “Only PDF files” option selected for “Attachments to be processed” will be sufficient. It is also possible to define what will happen if the system encounters a faulty barcode, or if the PDF file is missing a barcode altogether.

  • Additional attachments – Define what other files can be attached to the workflow instance. For example, it is possible to attach the contents of an email conversation as an EML file. It is also possible to define a template which will regulate what files can be attached – available formulas can be found in the contextual help (Fig. 6).

 Fig. 6 – Additional attachments filter contextual help


For this example, no additional attachments are necessary.

A sample configuration of the “General” tab can be found below (Fig. 7).

Fig. 7 – Sample configuration of the General tab


Advanced settings tab

This tab is divided into two sections:

  • “Restriction of supported email sender list” – Only emails received from senders defined in this data source will be processed.
  • “Limit of processed emails” – Set various limits on the number of processed emails per day and per iteration. Also set an expiry date for emails (emails older than the defined date will not be processed).

A sample configuration of the “Advanced settings” tab can be found below (Fig. 8).

Fig. 8 – Sample configuration of the Advanced settings tab


Barcode settings tab

The “Barcode settings” tab consists of the following sections:

  • “General” – Determine the contents of the barcode that the system will look for. In our example, the code added to the contract/agreement template has default contents so select “standard barcode”.
  • “Barcode search algorithm” – this section allows for customizing the way in which the system searches for barcodes in order to minimize the number of unrecognized barcodes. System allows for a defined number of samples/tries (maximum of 3) which will be taken before rejecting the barcode, and in which working mode will be used for each try. Examples of searching algorithms available from the menu are: “Sharp”, “Treat as picture”, “Dilate”.
    In this section, we also choose the order in which barcodes are searched for in the file (if we have more of them and of a different type) and we choose the input resolution of the files. After setting all the parameters we can test our configuration by clicking “Verify configuration” and selecting either a basic or full test.

A sample configuration of the “Barcode settings” tab can be found below (Fig. 9).

Fig. 9 – Sample configuration of the Barcode settings tab


Joining to elements settings tab

The “Joining to elements settings” tab contains two sections:

  • “Creating elements for unrecognized files” – here we define the form type, workflow, process and business entity for which a workflow instance will be started if the system doesn’t find the correct barcode in the PDF attachment. In our case, it will be an instance of the “Agreement” workflow. Also, we have to choose through which workflow path the system has to go to register the instance.
  • “Additional field settings” – this section is used to assign email data to a specific form field, for example, the sender address or title. A full list of available variables is available in the contextual help (Fig. 10).

Fig. 10 – Additional field settings contextual help


A sample configuration of the “Joining elements to settings” tab can be found below (Fig. 11).

Fig. 11 – Sample configuration Joining elements to settings tab


Saving the HotMailBox

After configuring the “General”, “Advanced settings”, “Barcode settings” and „Joining to elements settings” tabs we can save our HotMailBox by clicking “Save” on the top bar.

After successfully saving, a message will appear (Fig. 12) which gives information on what to do for the changes made in the HotMailBox to take effect.

Fig. 12 – HotMailBox save message.


Service configuration

After saving our HotMailBox we have to turn on the “Email/MailApproval inbox monitoring” option. To do this in the “System configuration” module on the left side branch we click on “Services configuration”, and then from “Services” choose the service for which our HotMailBox was defined (Fig. 13).

Fig. 13 – Service selection


After choosing our service, check the “Email/MailApproval inbox monitoring” box [1], then save changes in the service configuration [2]. For the HotMailBox to work properly, reload the service configuration [3].

Clicking “Load configuration” will bring up a confirmation window as reloading the configuration means stopping all active service tasks. Disrupted operations will be restarted when the service loads its configuration.

Fig. 14 – Service configuration


To check if the service loaded its new configuration correctly, choose “Local service status” on the left side branch, and then click the “Refresh” button on the top bar (Fig. 15).

Fig. 15 – Local service status


The HotMailBox is now configured correctly. When an email appears in the selected folder, the system will check whether it has any PDF attachments. Every one of those PDF files will then be searched for barcodes containing an instance ID. If the system finds one such barcode, it would attach this PDF file as an attachment to the corresponding Agreement workflow instance.


Leave a Reply

Your email address will not be published. Required fields are marked *