Completing tasks via E-mail

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Process wizard > Define Forms >

Completing tasks via E-mail


You can easily configure any manual task to be completed by the allocated user via e-mail. This functionality is known in Bizagi as E-mail integration

When E-mail integration is enabled for a specific task, its allocated user will receive an e-mail and all he/she has to do is click on any of the buttons included in that e-mail and enter comments if applicable.

Buttons included in that e-mail typically allow the user to decide on the path a case in Bizagi should take (i.e commonly approving or rejecting a request).


Email integration7



How E-mail integration works with Bizagi?

To configure the E-mail integration feature, you need to first set up in your Bizagi project the connection to your corporate E-mail server, so that any type of e-mail notifications can be sent by processes in Bizagi (via the SMTP protocol).

You will then need to set up how Bizagi will fetch the "Accept or reject" response at the corporate E-mail server (sent after the user clicks on either option presented in that e-mail).


Once Bizagi interprets the response given by the user, the task will be completed, relevant comments will be stored in the data model, and the process workflow will move on to the next task (accordingly, by following the path enabled by the particular decision).


The following image illustrates how E-mail integration works at runtime and the protocols it involves:




1. SMTP Notification

A process in Bizagi sends an e-mail notification, to allow the completion of that task via e-mail.

2. New Email

The allocated end user receives the new e-mail (client applications installed in the end users' laptops will retrieve it from the E-mail server).

The end user will click on an option presented in that e-mail, that decides upon the next step that the process should take.

3. Approve / Reject

The response is sent to a specific mailbox service in which Bizagi uses a dedicated account.


Bizagi listens to response arrivals (unread messages), so that it fetches them via standard protocols such as IMAP, POP3, or direct Exchange connections.

The response is processed by Bizagi to store comments and to enable the next step of the workflow.



When should I use this feature?

It is important that you adequately select tasks which are aligned to this feature's purpose.

This means that the concept behind this feature is not applicable to all tasks, and you will need to accurately define which tasks will use it.


Tasks of your processes which are applicable, or best candidates for the E-mail execution feature's use, are those which:


Are manual tasks (those requiring user intervention).


Present different choices that directly determine the path taken by the workflow (which task is enabled next).

In other words, tasks which are typically followed by gateway evaluating the choice that was made.

In Bizagi, this means that tasks should use the form buttons feature.

For more information, refer to Form buttons.


Require a small amount or user interaction (i.e no validations or sophisticated behavior in the user interfaces), and are mainly oriented to Approval or Rejection decisions.

This is so because the body of the e-mail sent to the user, will namely contain strictly relevant information, and 2 or more options reflecting possible decisions (such as Approve or Reject or others, all this as previously defined in a template).

The actual e-mail WILL NOT present any controls that were designed for the user interfaces of that task. This would still be an e-mail and not a user interface.


Do not require a large amount of input from the user (i.e, attachments are not allowed, nor entering information into tables).

The E-mail execution feature allows the user to enter general comments (or observations regarding the decision), which are stored by Bizagi in a pre-defined attribute of the data model.


Are allocated to one user at a time.

If there is more than one user that can initially work in the task (up for the first one who works on it), no e-mails will be sent.

In other words, this feature's concept is not applicable when a task can be performed by anybody (i.e using the "Everyone" configuration for performers).




Before moving on, and in order to ensure that you can explore, configure or verify this feature, you will need to previously set up the configuration in Bizagi to connect to your different e-mail services.

Note that you may need assistance from your IT department for such configuration described next:


1. Before configuring the use of E-mail integration, ensure that your processes can send e-mail notifications through your corporate E-mail server.

Such E-mail server needs to be compliant to the SMTP protocol, and its connection is to be configured in Bizagi as described at E-mail server configuration.


2. Once you ensure that Bizagi processes send e-mails, proceed to configure the connection settings to the mailbox service from which Bizagi will fetch responses from users.

At this point you will need a dedicated e-mail account solely for Bizagi's use.

Important considerations for this dedicated account are:

It should be considered as a service account.

No user should use this account nor check e-mails of it, because only unread e-mails are fetched by Bizagi and then marked as read.

It is strongly recommended to use one account per each Bizagi environment (one for development environment, one for testing, and one for the production environment).



Though the mailbox service is usually provided by the same services of a corporate E-mail server, it is possible to use a different mailbox service, which is not part of your corporate E-mail server.

The relevant aspect for such service is that it needs to support renown protocols such as POP3, IMAP or using an Exchange connection (widely used mailbox services such as those provided by Gmail, Exchange or Lotus are supported).


To configure the connection settings to the mailbox service, follow these steps:

Open the Environment configuration and locate the Popular tab to configure the E-mail integration section.


Email integration_Environment


Consider configuring the parameters according to the table presented below, and considering your different environments:





Enable lookup email

Tick this checkbox in order to allow Bizagi to use the E-mail integration feature for any of your tasks. This setting enables Bizagi client (POP3/IMAP/Exchange) to retrieve response e-mails (it will not disable each task sending e-mails to users with the response options unless you disable these from each task's options).

Enable SSL

Applicable to POP3 and IMAP protocols.

Tick this checkbox in order to enforce that Bizagi uses the E-mail integration feature through a secure channel for POP3 and IMAP (recommended).


Notice that Exchange server are already enforced to use HTTPS.

Connection type

Choose from the commonly used protocols for clients to fetch e-mails from a server (widely supported), such as POP3 or IMAP. Use Exchange if that is your specific server.

When choosing POP3 or IMAP, use the Enable SSL and Port settings according to what instructed by your IT department.


Applicable to POP3 and IMAP protocols.

The port number employed by the protocol.


Specify the designated account for Bizagi's purpose.

Such account is to be checked exclusively by Bizagi.

Host / Mailbox service

Enter the name of the server that hosts the e-mails for the given account. Use a mailbox service setting when connecting to Exchange.


Enter the authorized username that connects to your host/mailbox service.


Enter the password for that authorized username.



Recall that at this point you need to have already configured the connection to your SMTP server as shown above.


If you plan on using Gmail as the Mailbox service where Bizagi picks up response e-mails, either for your operating environment or to evaluate and test this feature, refer to the example and reference as presented at Configuring E-mail integration using Gmail.



What you need to do in Bizagi

Once prerequisites are met, for any amount of tasks in which you wish to provide the E-mail integration feature, the following illustrates an outline of the steps you need to carry out:


1. Define or prepare the tasks that will use E-mail integration.

Recall that not all tasks are immediately available for this feature, since you will need to consider which ones are good candidates and have the required configuration.


2. Enable that task to use E-mail integration.

Allow the use of E-mail integration once such tasks have the required configuration.


3. Define the e-mail template and configure its use for the appointed task.

Explicitly define the subject and body of the e-mail notification, and any other relevant information.


4. Configure additional parameters to handle the response.

Such parameters consider where to store comments, treatment for failed responses, etc.




To illustrate the required configuration, we will use a Vacation Request process as an example.

In such process, typically the requester's boss or overseer, must make a decision regarding if the vacation leave request is approved, rejected or if additional information and changes are needed.

As the requester submits his/her request, that requester's boss is allocated with the following task (called Approve Vacation Leave request), where the decision is made.


Email integration_process


Note that according to this example's process, 3 different paths are enabled afterwards.

This means that when the e-mail sent to the requester's boss should present all 3 buttons:

Approve, which would enable the workflow to continue with the Send Approval Message task.

Reject, which would enable the workflow to continue with the Send Rejection Message task.

Request changes, which would enable the workflow to go back to the Register Vacation leave request task.


To enable E-mail integration for this example, follow the guided steps.


1. Define or prepare the tasks that will use E-mail integration

Recall that not all tasks are immediately available for this feature, since you will need to consider which ones are good candidates and have the required configuration.


Note that within the form of that task, the Email configuration option will be enabled while having an active Form buttons configuration:


Email integration1


If your form does not already use form buttons, then you may configure them.

To do so, ensure you include one button for each of the possibilities, and use a Next-action configuration for each button.


For instance, for the Approve button, we will use a Rule that sets the Approved state to "Approved" (code AP), and executes a Next action in Bizagi that completes the task.


Email integration4



The expression for this rule, for example as needed in the Vacation Leave request process available at the Process Xchange is:

Code = CHelper.getEntityAttrib("RequestState","idRequestState","Code = 'AP'");

<VacationRequest.VacationLeaveState> = Code;


Similarly, the Reject button will use a Next-action as well though its rule would be slightly different to consider a Rejection reason:


Email integration5


Finally, the Request Changes button is set in the same fashion as the Approve button:


Email integration6



The expression for this rule, for example as needed in the Vacation Leave request process available at the Process Xchange is:

Code = CHelper.getEntityAttrib("RequestState","idRequestState","Code = 'RC'");

<VacationRequest.VacationLeaveState> = Code;


2. Enable that task to use E-mail integration

Allow the use of E-mail integration to activate the feature for the specific task (if deactivated at any time, Bizagi will not send e-mails for that specific task).

To do so, click on the Email configuration option and tick the first property called Enable email execution:


Email integration2


3. Define the e-mail template and configure its use for the appointed task

Explicitly define the subject and body of the e-mail notification, and any relevant fields which are informative for the user making the decision.

To do so, click on Edit message to define the e-mail template.


Email integration3


Note that you do not need to worry about the options presented to the user (Bizagi includes by default the options as defined by the form buttons).

This means that if you choose not to configure an e-mail template, an e-mail will be sent presenting only in its body the different options.


4. Configure additional parameters to handle the response

Tick the check boxes to notify back the user if that e-mail's response was successfully processed, or if there were any problems.

Enable the Receive success notification or Receive failure notification accordingly to be notified about its particular execution.


Additionally, define where comments entered by the user given will be stored in the data model.

When done, click Save to close the configuration window.




To illustrate how our example works in runtime, assume that a user called Henry Jacobs submits a Vacation request.

His boss, John Peterson will then receive this e-mail:


Email integration7


All John Peterson will do is click on any of the options available: Approve, Reject or Request changes.

When doing so, a new e-mail is sent back.


Note that the same e-mail above corresponds to the appointed task that John Peterson may locate at the Work portal as well:


Email integration8



The e-mail sent back will use the appropriate subject to be handled by Bizagi (the choice inside brackets followed by the name of the activity), along with additional information that should not be modified (the recipient having the account as used by Bizagi).

The user may input additional comments at the beginning of the e-mail:


Email integration_response




Recall that tasks enabled to be completed via e-mail, will still be also available to be completed through the Work Portal.

This means that if Bizagi receives a response via e-mail, then the task will no longer be available in the Work Portal, and similarly, whenever the user completes a task through the Work Portal, then any e-mails already sent will no longer be valid (such e-mail replies will log an error).

Whenever fields within the Form are required to be filled-in, it is strongly recommend to rely on Rules (as available in the Button's configuration) in order to automatically set those values to these fields.

Note that responses are processed by the Scheduler service in Bizagi.

Therefore, it is important that you ensure that the Scheduler is in a started status.

This feature has been verified with Outlook365 and Outlook 2013, as well as with Gmail and Yahoo. Other providers or versions have not been officially certified as well as the use of web clients such as Owa (which is not supported).

For this feature's adequate working, ensure both that the ports that you use for the mailbox have adequate access rights and that this mailbox is not the same one as the one assigned for the user when completing a task via e-mail.

You may not use a same mailbox in for multiple Bizagi projects nor for multiple Bizagi environments of a same project.






Monitoring and troubleshooting

When using this feature, it is strongly recommended that an administrator watches over the E-mail integration and adequate access from Bizagi to the mailbox service (and its designated account).

Logs having further detail can be found as described below.


The logs recorded for Email configuration will be located in Windows Event Viewer.