Target audience: Modelers
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:
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
|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.|
|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 |
|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.|
|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:
<channel-definition-key> needs to be replaced with the appropriate key.
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:
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.
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
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.
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:
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:
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: