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 attributes by yourself.
However, for email there is a fixed set of field names that can be chosen.
In case the needed field is not mapped directly, you can also use the
rawMailBytes to extract it inside your code or process.
Let's create an event with the key
The following fields can be used out of the box:
|from||string||Sender of the email.|
|subject||string||Subject of the email.|
|subjectCorrelation||string||Concatenated result of the subject matching regex pattern, defined in the channel definition (see later)|
|receivedDate||string||Date when the email was received.|
|sentDate||string||Date when the email was sent.|
|to||json||All receivers of the email as mentioned in the |
|cc||json||All email addresses copied as mentioned in the |
|bcc||json||All email addresses blind copied as mentioned in the |
|customHeaders||json||List of all other custom headers.|
|content||string||Plain text content of the email.|
|contentHtml||string||The HTML content of the email.|
|attachments||json||List of all attachments with an object containing |
|rawMailBytes||string||The complete email as received from the email server. Can be used to attach the email as a document.|
You don't need to use all fields, it's enough to define the fields needed in your model. The event definition might look like this:
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:
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.
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.