Completing tasks via Email

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Process wizard > Define Forms >

Completing tasks via Email


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

When Email integration is enabled for a specific task, its allocated user will receive an email and then, the user can click any of the buttons included in the email and enter comments.

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


Email integration7



How Email integration works with Bizagi?

To configure the Email integration feature, you need to first set up in your Bizagi project the connection to your corporate Email server, so that any type of email 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 Email server (sent after the user clicks on either option presented in that email).



Bizagi will check if the response is sent using the assignee's email address before interpreting it.


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 Email integration works at runtime and the protocols it involves:




1. SMTP Notification

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

2. New Email

The allocated end user receives the new email (client applications installed in the end users' laptops will retrieve it from the Email server).

The end user will click an option presented in that email, 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 Email 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 email 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 email WILL NOT present any controls that were designed for the user interfaces of that task. This would still be an email 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 Email execution feature allows the user to enter general comments (or observations regarding the decision), which are stored by Bizagi in a predefined 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 emails 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 make sure 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 email services.

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


1. Before configuring the use of Email integration, make sure that your processes can send email notifications through your corporate Email server.

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


2. Once you make sure that Bizagi processes send emails, 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 email 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 emails of it, because only unread emails 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 Email server, it is possible to use a different mailbox service, which is not part of your corporate Email 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 Email 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 Email integration feature for any of your tasks. This setting enables Bizagi client (POP3/IMAP/Exchange) to retrieve response emails (it will not disable each task sending emails 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 Email 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 emails 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 emails 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 emails, either for your operating environment or to evaluate and test this feature, refer to the example and reference as presented at Configuring Email 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 Email integration feature, the following illustrates an outline of the steps you need to carry out:


1. Define or prepare the tasks that will use Email 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 Email integration.

Allow the use of Email integration once such tasks have the required configuration.


3. Define the email template and configure its use for the appointed task.

Explicitly define the subject and body of the email 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-ail 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 Email integration for this example, follow the guided steps.


1. Define or prepare the tasks that will use Email 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, make sure 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 Email integration

Allow the use of Email integration to activate the feature for the specific task (if deactivated at any time, Bizagi will not send emails 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 email template and configure its use for the appointed task

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

To do so, click on Edit message to define the email 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 email template, an email 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 email'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 email:


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 email is sent back.


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


Email integration8



The email 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 email:


Email integration_response




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

This means that if Bizagi receives a response via email, 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 emails already sent will no longer be valid (such email 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 make sure 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, make sure 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 email.

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

The emails sent through this feature use HTML format. If the recipients use plain text format, the form buttons are displayed as a link which may make it difficult to recognize them.



Monitoring and troubleshooting

When using this feature, it is strongly recommended that an administrator watches over the Email 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.