Receive Email

Target audience: Modelers

Introduction

This guide explains how you can receive emails from an IMAP server, pass them into process or case instances (with or without using correlation based on instance data).

You can use the event registry to orchestrate events. Normally, those events are coming from a message bus (like Kafka, RabbitMQ, ActiveMq, etc.). For some use cases however, you would also like to receive emails and correlate them to your processes or cases. This also means that all concepts and modeling capabilities available when working with events, apply to incoming emails too.

Email Event Model

To represent an incoming email you first need to create an event model that captures the data.

Typically, you are able to specify all the event model attributes by yourself. However, for email there is an out-of-the-box event model that can be used.

Go to your app model, click on Add model, select the Include an existing model in the app in the first step and then find the system event model for email:

note

The event model is part of the app model, but it won't be deployed to a Flowable Work system, as a system model (like the mail event model) is already deployed by default there.

Setting up the Channel Model

The channel model is the part which is reading the emails from your IMAP server. You need to create a channel of the type Inbound with the implementation E-Mail. Then you have a few fields which you can specify:

Name	Description	Example
IMAP URL	Connection string for IMAP. It starts with a protocol, followed by the hostname and then the name of the folder to read.	imaps://my.mail.host/INBOX
Event key	The event to trigger, this event you need to create and all the occurrences of this specific event will be triggered for this channel definition.	emailEvent would match the event created in the section above.
Subject correlation pattern	Can be used to correlate emails to your specific case or process instance. Inside a process instance you can also use the result of the pattern to filter emails, since the subjectCorrelation is null in case the pattern did not match. The subject correlation is computed based on all the regex groups.	.*\[(ABC-[0-9]+)\].* would search for patterns like [ABC-42] in the subject and extract ABC-42 into the subject correlation attribute. It will be null in case the pattern does not match.
Should delete message	Whether messages should be removed from the server.
Should mark messages as read	Whether messages should be marked as read.
Polling rate	That's how often Flowable is going to poll the specific mail server. That's also, the delay you might have while receiving the message. You can specify a duration with the ISO 8601 standard.	PT15M would read emails every 15 minutes
Username	The user to authenticate against your IMAP server. This might be the email address.
Password	The password to authenticate against your IMAP server.

A complete configuration could look like this:

To avoid saving the credentials of your mail server inside the channel configuration, you can also configure Spring Boot properties of your Flowable Work application instead:

flowable.eventregistry.mail.channels.<channel-definition-key>.authentication-username=
flowable.eventregistry.mail.channels.<channel-definition-key>.authentication-password=

The <channel-definition-key> needs to be replaced with the appropriate key.

Token-based authentication

In case token-based authentication is required (e.g. XOAUTH2), please have a look at the end of this article. Appendix: Token-based authentication (Microsoft Office 365)

Using the Event in a Process

This section covers a simple use-case to receive events in a process.

A simple example process which is started by an email would look like this:

When you insert an event registry start event and click on it, you can specify channel and event:

Opening the Configured to receive to 'emailEvent' will show you the detailed event configuration. Here, you can specify if you would like to create an instance for every event or for each event which correlates. In addition, you can specify which attributes should be stored in which variables:

The above example would start only for each email with the same correlation one process. Further incoming emails would stay unhandled, since the task is on only create one instance and there is no other event. The On receiving this event property can be changed accordingly if something else is needed.

note

In case the needed field is not mapped directly, you can also use the rawMailBytes to extract it inside your code or process.

Attaching the Email to our Process

Now we can also use the Create Document Task to generate a content item out of the email we just received. Therefore, we use the raw bytes the event is giving us.

Let's add a create document task to our process:

The configuration of the task is easy, you just need to give the email a name and pass in the raw bytes and set the content type to message/rfc822 (this will be suggested as E-Mail).

Looking at our new created instance we will see in the Documents tab an attachment with our email:

Attaching documents to our Process

In a next step, we can also add every single email attachment as a content item to our process. The attachments field is null in case we do not have any attachments. In case it's not null, it's a collection which we can iterate over, for example with the Create Document Task. This can be used to create one content item per document.

Once you now receive an email, you will find the email including the attachments in your Documents tab:

Further reading

Of course, this example is a simple process. More advanced scenarios including email can easily be imagined. For example, you can use a case model to make your email handling smarter by using the typical 'if-this-then-do-that' pattern that's easy to do with CMMN:

For more complex scenarios, please also checkout the Getting Started with Channels and Events How-To which is covering more details about the event registry.

Appendix: Token-based authentication (Microsoft Office 365)

v3.12.5+ v3.13.0+

Some Email providers like Microsoft Office 365 require a token-based authentication instead of a password-based authentication. This section describes how to configure token-based authentication, to access your Email account for Microsoft Office 365.

In order to obtain access tokens, you need to register and configure your application in the Microsoft Azure Portal first. We published an extensive blog post about this topic, which covers in more detail.

Once the app is setup, you need to register the Spring Security OAuth2 client provider and client registration to your application.properties file. The following properties showcase the configuration for the OAuth2 client credentials flow:

spring.security.oauth2.client.provider.exchange-server-imap.issuer-uri=https://login.microsoftonline.com/<azureTenantId>/v2.0
spring.security.oauth2.client.registration.exchange-server-imap.client-id=<application_client_id>
spring.security.oauth2.client.registration.exchange-server-imap.client-secret=<client_secret>
spring.security.oauth2.client.registration.exchange-server-imap.scope=https://outlook.office365.com/.default
spring.security.oauth2.client.registration.exchange-server-imap.authorization-grant-type=client_credentials

The exchange-server-imap part of the properties is the client registration id. It is a custom name and can be named as desired. Multiple providers and registrations are possible to authenticate against multiple OAuth2 endpoints. You can find the endpoints of the issuer-uri, alongside all the other available endpoints for a registered app in the Microsoft Azure Portal for your app.

The following screenshot shows the configuration for the Email inbound channel:

The password uses a Spring Expression Language expression to resolve the access token, which is obtained for the client registration shown above. The expression parameter 'exchange-server-imap' maps to client registration id above. Token expiration is handled automatically by the implementation. The custom properties are required to activate XOAUTH2 and to force the disabling of plain authentication (required for Office 365 as of writing this article).

In case something goes wrong, add the following additional custom properties to the configuration above:

• mail.debug to true
• mail.debug.auth to true