HotMailBoxes – Starting a workflow for an attachment

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

Functionality description

WEBCON BPS Designer Studio allows us to create a 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: starting one workflow for a specified attachments

The organization uses a workflow for handling invoices. For every e-mail that arrives in the inbox (and goes to the correct folder), each PDF file found in those emails will trigger a new “Invoice” workflow instance to start. The workflow form will load data from the e-mail, including the title, received date, mail sender and also attach the PDF file for which the specific instance was started.

The workflow through which incoming Invoices will be processed can be found below (Fig. 1).


Fig. 1 – Invoice workflow


  • Registration – Automatic system step done at the workflow start for each of the PDF files attached to the email sent to the HotMailBox.
  • Verification – In this step, a user is assigned to verify if the invoice data is correct.
  • Approval – In this step, the invoice is accepted or sent back to verification for re-evaluation.
  • Archive – Positive end 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 – Creating a new HotMailBox.


General tab

The General tab of the HotMailBox contains 5 sections to fill:

  • „HotMailBox” – This section contains the HotMailBox name and server on which it will run. Additionally, a description can be added. In order for it to work, the “Active” checkbox must be marked.
  • „Connection settings” – here you input the connection parameters with the mailbox. Select “Use custom inbox settings”, choose server version and enter its address. Then enter the login credentials of the user through which the connection to the server will be established. Following tools might be helpful during the mailbox connection configuration:

„Autodiscovery” (Fig. 3) helps by detecting server name based on user data and „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 „Start one workflow per attachment”. Then in “Attachments to be processed” choose which files should be added to workflow and under “Template for created attachment names” define how 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.

  • 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


Starting workflow settings tab

This tab has two sections:

  • Creating new process elements – Here we define the workflow, process, form type and business entity for which the instance will be started. In our case, it will be an “Invoice” workflow instance. Also, we have to choose through which workflow path the system has to go to register the instance.
  • Additional fields settings – Assign e-mail data to specific workflow form fields, like e-mail sender or the title. The full list of available variables is available in the contextual help (Fig. 9).


Fig. 9 – Workflow instance field variables contextual help.


Sample configuration of the „Starting workflow settings” tab can be found below (Fig. 10).

 Fig. 10 – Sample configuration of the „Starting workflow settings” tab.


Saving the HotMailBox

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

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

Fig. 11 – HotMailBox save message.


Service configuration

After saving our HotMailBox it is needed to turn „Email/MailApproval inbox monitoring” box on. In order to do that in “System settings” module on the left-side branch, click on “Services configuration” and then on “Services” and choose our service (Fig. 12).


Fig. 12 – Service selection.


After choosing our service, check the “Email/MailApproval inbox monitoring” box [1] (see fig. 13), 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. 13 – 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. 14). A log “Restart service roles completed” should appear.

 Fig. 14 – Local service status.


Our HotMailBox is now correctly configured. After an email with at least one PDF attachment arrives in the correct folder of the inbox, a new ‘Invoice’ workflow instance will be launched. A separate workflow instance will be launched for every PDF attachment found.

Leave a Reply

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