Introducing the Flowable Event Registry
Blog: Flowable Blog
In Flowable 6.5.0 a new engine has been added: the Flowable Event Registry. This enables receiving and sending events from any source, with out-of-the-box support for JMS, Kafka and RabbitMQ. In addition, receiving events is also possible through HTTP. This article describes how to start using the Event Registry using the Flowable Modeler and Task application and Apache ActiveMQ to be able to receive and send JMS messages.
Let’s start with designing a BPMN process with the Flowable Modeler with an Event Registry start event as the starting point.
When an event is received the First task user task is the next step in this example BPMN process. But let’s start with looking at the configuration of the start event.
The first part is the definition of the event key and name which identify the incoming event. The same is necessary for the channel key and name. In this example, the event will be received on a JMS queue with the name testQueue. The last part is the configuration of the event payload parameters, which defines how the event parameter values are mapped to process variables.
In this example, two event parameters will be mapped to a process variable, the customerId and productNumber values. In the event payload dialog it’s shown that the customerId parameter is mapped to the customerVar variable and the value is of type String. So in the process instance context the customerVar and productNO variables will be available.
n this example, two event parameters will be mapped to a process variable, the customerId and productNumber values. In the event payload dialog it’s shown that the customerId parameter is mapped to the customerVar variable and the value is of type String. So in the process instance context the customerVar and productNO variables will be available.
When the process instance is started with the myEvent event message, the first wait state is the user task First task. This user task has a boundary event registry event attached to it. This means that when an event is received through the event registry, the boundary message will be triggered and executed. In this case the user task will be cancelled and the next user task Boundary task is created. Let’s look at the configuration properties of this boundary event registry event.
As you can see the configuration is similar to the start event we discussed before. In this case a boundaryEvent event is expected to arrive at the boundaryQueue JMS queue. The main difference is the correlation parameters configuration. When multiple process instances are running of this example process definition, how can an incoming boundaryEvent message be matched against one of the running process instances. This is what is defined with the correlation parameters.
In the boundaryEvent event message a customerId property value is required and the value is matched against the customerVar variable of the process instance. This variable value was set by the event message that started the process instance. In this case, only one correlation parameter if configured, but it’s also possible to have multiple correlation parameter values that need to be match.
In the engine this works with event subscriptions, similar to a message and signal event. When the First task user task is reached, then the boundary event registry event logic will create an event subscription with the correlation parameter values in the configuration value of the event subscription. When a new boundaryEvent event message is received from the BoundaryQueue JMS queue, the event is matched against a event subscription that listens to the boundaryEvent event type and a configuration value that is equal to the customerId event property value.
The final task to be discussed in this process model is the Send event task. The type of this task is the same as the name it’s given in this example, e.g. Send event task. This task can be used to send out an event to the event registry with a JMS, Kafka or RabbitMQ destination. In addition, it’s also possible to wait for a response of the outgoing event as an incoming event that is similar to the start event and boundary event we discussed before. This is also similar to the triggerable service task that is available in Flowable since version 6.4.0.
For the outgoing event a message is sent to the sendQueue JMS queue, and it has one event property defined in the event payload.
The customerName variable will be sent in the event payload with a property name. In this example we will also wait for a response event message before continuing to the last task in the process model.
An event of type triggerEvent is expected to arrive on the triggerQueue JMS queue. For the correlation parameters, again we expect a customerId event property to match the customerVar process variable, just like it was the case with the boundary event. And 2 event properties will be set as process variable: the event property productName will be set as a product process variable and the event property amount will be set as a productAmount process variable. After receiving and processing this event, the last user task After send task is created.
With the process modeled we can now start with moving to creating a process instance and test the process model. Make sure that for the Flowable Task application the following Spring properties are set (for example in the flowable-default.properties file or an application.properties file on the classpath):
#Enable and configure JMS
flowable.task.app.jms-enabled=true
spring.activemq.broker-url=tcp://localhost:61616
If you don’t have Apache ActiveMQ installed then download it from http://activemq.apache.org/components/classic/download/. You can start it with the activemq.sh or activemq.bat scripts in the bin folder of the Apache ActiveMQ installation.
Now let’s start the Flowable Task application and create an app model in the Flowable Modeler and add the example process model to the newly created app. In the app details view you can then publish the app to the Flowable Task application. This will deploy the example process model to the BPMN engine, and the event registry start event will create an event subscription. In addition it will create a JMS listener to the testQueue JMS queue.
Now we can send an event message to the testQueue. Apache ActiveMQ provides a web console that allows us to send a message and read a message from a JMS queue. Open a browser and go to the http://localhost:8161/admin/ page. The default login is admin/admin. Now click on the Queues tab and lookup the testQueue in the list. It should have been automatically created by Apache ActiveMQ. On the right hand side there’s a Send to action link that opens a view where we can enter the event message content. Remember that the start event expects an event message with a customerId and productNumber event property. So in the message body let’s fill-in the following JSON message and click the Send button:
{
"customerId": "123455",
"productNumber": "flw123"
}
In the Flowable Task application, navigate to the application you deployed from the Flowable Modeler and you should see a task with a name of First task in the task list. In the processes list there should also be one new process instance and the diagram should look like this:
We can now trigger the boundary event by sending an event message to the boundaryQueue JMS queue. The customer id value should match the value that we sent with the start event message, to match the correlation configuration. Let’s first send a message with a different customerId value.
{
"customerId": "123456",
"customerName": "John Doe"
}
You can use the ActiveMQ web console again, and this time send it to the boundaryQueue. As you can see when refreshing the Flowable Task application task list view, nothing has happened with the process instance state. Now let’s trigger the boundary task with a matching customerId value.
{
"customerId": "123455",
"customerName": "John Doe"
}
This time the correlation parameter matches and the process instance moves on to the Boundary task user task. Just complete this task in the Flowable Task application and now the send event task will send out an event message to the sendQueue JMS queue containing the name value. You can see the message content when clicking on the sendQueue link in the ActiveMQ web console and selecting the message in the list.
Now we have one event message left, which should trigger the send event task to continue to the last user task in the process definition. An event message containing the customer id, product name and amount needs to be sent to the triggerQueue with the customer id matching the correlation value of the running process instance.
{
"customerId": "123455",
"productName": "Flowable lego block",
"amount": 10
}
Send it again with the ActiveMQ web console and check if the After send task is available in the Flowable Task application. This time, the user task also has a form attached to it, showing the process variables from the event messages that we sent.
This completes the overview of how to use the new event registry functionality with a BPMN process example. In a next article we will have a look at how we can do a similar example, but now using a CMMN case example together with the event registry.
If you would like to import the example process and app model directly into the Flowable Modeler, you can use this zip file and import it.
Leave a Comment
You must be logged in to post a comment.
