How Flowable and RabbitMQ integration with the event registry works
If your business events arrive on RabbitMQ and must start, advance or correlate Flowable processes and cases, the supported way to connect them is the Flowable Event Registry. The engine supports RabbitMQ out of the box, alongside JMS, Kafka and HTTP, and it uses those events inside BPMN and CMMN models. Two kinds of definition do the work. An *event definition* declares the payload fields the engine reads and the correlation parameters that match an incoming message to a running instance. A *channel definition* binds that event to a broker destination, so the engine knows which RabbitMQ queue or exchange to consume from or publish to. Your first decision is therefore not which library to write, but which business keys identify a process instance across the messaging boundary.
Agree the payload contract and the correlation keys with the team that owns the RabbitMQ topology before any model is built. Confirm which fields each message carries, whether they are stable across producers, and whether one message should start a new instance or be routed to an existing one. Ask who owns queue declarations, dead-letter handling and retry policy, because channel definitions point at destinations that the messaging team must provision. The configuration keys and channel options for RabbitMQ are described in the event registry documentation linked from this page, and the exact connection settings for your Flowable version should be checked there rather than assumed. The topic facts supplied here do not cover other connector options, so confirm any alternative adapter with Flowable before you plan around it.
What you need before connecting Flowable to RabbitMQ
Most RabbitMQ integration problems start before any event is sent, with the engine version, runtime baseline, database and broker ownership not agreed. The cards below cover what to settle with your platform team and your messaging team before you define event and channel models.
Flowable engine version and runtime baseline
Pick the Flowable release first, because it sets the Java, Spring and Jakarta baseline for everything else. Flowable 8.0.0 moved to Spring Framework 7 and Spring Boot 4 and dropped support for Spring Boot 3, so an application still on Spring Boot 3 cannot take that release without upgrading. Flowable 7.0.0 required Java 17, so confirm the JDK your build and runtime images use before choosing a version.
Supported database type
The event registry stores its deployments and runtime data in the same database as the engines, so the database must be one Flowable supports. The configuration docs list H2, MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server. Confirm which of these your database team operates, and if you choose MySQL, confirm the version is at least 5.6.4 so timestamps keep millisecond precision.
RabbitMQ account and vhost ownership
Agree who owns the RabbitMQ virtual host, the exchanges and the queues that Flowable will bind to. Ask the messaging team for a dedicated vhost, a service account with permissions limited to the declared exchanges and queues, and a named owner for changes. Clarify whether Flowable may declare exchanges and queues itself or whether the messaging team provisions them from a reviewed definition.
Network paths and firewall rules
Map every connection the Flowable runtime needs: the application nodes to RabbitMQ on its AMQP port, the nodes to the database, and any load balancer or proxy in between. Confirm these paths in each environment, including staging and disaster recovery, because a rule that works in one environment often fails in another. Ask the network team to document the paths before the first test deployment.
TLS certificates and trust stores
Decide whether client connections to RabbitMQ use TLS, and if so, which certificate authority signs the broker certificate. Ask the security team who issues and renews the client certificates, where the trust store lives, and how a rotation reaches every Flowable node without a long outage. Confirm the expected certificate chain with the messaging team before the first connection test.
Events and channels owned by one team
Name the team that approves event definitions and channel definitions, because payload fields and routing keys become a contract between process models and other systems. Agree the payload schema, correlation fields and the naming convention for exchanges and queues in writing. Changes to these items after go-live affect running instances, so record who signs off on each change.
Configuration sequence for the RabbitMQ event registry channel
This sequence takes a RabbitMQ destination from an empty broker to a working Flowable event registry channel that starts or correlates process and case instances and publishes outbound events. Each step ends with a check that confirms the engine and the broker agree before the next step begins.
Agree the event contract with the messaging team
Before any configuration, the Flowable team and the RabbitMQ owners agree on the exchange, queue, routing key, message format and payload fields for each inbound and outbound event. The Flowable team writes these down as the payload fields and correlation parameters that the event definition will declare. The step is done when both teams sign off a single document listing every event name, its direction and its sample JSON payload.
Create the RabbitMQ exchange, queue and bindings
The messaging team declares the exchange and queue in the environment Flowable will use, then binds the queue to the exchange with the agreed routing key. Keep dev, test and production names distinct so that a test message cannot start a production instance. The check is a management view or CLI listing that shows the binding exists with the expected routing key and that the queue is durable where your policy requires it.
Define the event definitions
In the event registry, the Flowable developer creates an event definition for each inbound and outbound event. Each definition declares its payload fields and the correlation parameters that route a message to the right instance, such as an order identifier. Deploy the definitions with the engine's repository service so they are versioned like other process artifacts. The check is that the deployment appears in the engine's event definition list with the expected field names.
Bind each event to a RabbitMQ channel definition
Create a channel definition for each event that names the RabbitMQ destination and sets the inbound or outbound direction. The binding must match the queue and routing key agreed in the earlier steps. Confirm that the channel points to the correct environment, because a copy-paste error here is the most common reason messages go to the wrong queue. The check is that the channel deploys and the engine reports it as active without startup errors in the logs.
Attach start events and boundary triggers in the models
In the BPMN process, the developer adds a start event that references the inbound event definition, or a boundary event on a waiting task that waits for a correlated message. In CMMN, the same event can drive an event listener on a stage or case plan item. Map incoming payload fields to process variables so later tasks can use them. The check is that the model validates and deploys, and the deployed definition lists the event reference in its model view.
Add send event tasks for outbound messages
Where a process or case must notify another system, the developer adds a send event task that references the outbound event definition and maps process variables into the payload. Agree with the messaging team which failures should retry and which should raise an incident, since a failed send inside a transaction behaves differently from one after a commit. The check is a test run where the task completes and the message appears on the bound RabbitMQ queue with the expected fields.
Publish a test message and confirm the start or correlation
Publish a message with a known correlation value to the inbound queue from the RabbitMQ management tool or a script. Then query the engine for a new process instance, or for an existing instance waiting on that correlation value, and check its variables against the payload. Repeat with a message that matches no instance to confirm the engine rejects or logs it as your design intends. The step closes when both the start path and the correlation path produce the expected result.
Verify failure handling and record the configuration
Test a malformed payload, a missing correlation field and a broker outage, and record how the engine and the broker respond to each. Confirm that failed inbound messages leave evidence your operations team can find, and that retries do not duplicate process starts. Store the event definitions, channel definitions and test results in version control with the model deployment so the configuration can be reproduced in another environment. The step closes when the failure results are documented and the configuration is committed.
Designing correlation parameters so each message reaches the right instance
Correlation parameters decide which running instance a RabbitMQ message reaches, so they are the most consequential design choice in the inbound half of this integration. In the Flowable event registry, an event definition declares the payload fields and the correlation parameters, and the engine uses the values of those parameters to match an incoming message to a process or case instance. A channel definition only binds that event to a RabbitMQ destination, so a wrong key in the event definition routes messages to the wrong place even when the broker wiring is correct. Before building, agree the key with the team that publishes the messages, and confirm in the Flowable event registry documentation how the engine treats a message whose key matches no instance or more than one.
A good correlation key is a business identifier that the publishing system already holds and that stays stable for the life of the case, such as an order number, claim reference or customer application ID. Avoid values the engine or broker generates at runtime, such as process instance IDs, RabbitMQ delivery tags or message IDs, because the publisher cannot know them when it sends the first message and they do not describe the business object. Illustrative example: a claims process started by a claimReference field and later correlated by the same field from a document-received message, so the publisher needs no knowledge of Flowable internals. Confirm with the messaging team whether the key is unique across the business domain and whether any message can carry a missing or empty value.
Duplicate and out-of-order messages affect matching in different ways, and RabbitMQ does not remove the need to plan for them. A redelivered message that correlates to an instance already past the waiting state may match nothing, or may match a later instance if the key is reused, so the model should tolerate messages that arrive when the process is not waiting for them. Out-of-order delivery can make a completion message reach an instance before the start message has created it. Decide whether such messages are rejected, retried or parked, and confirm with the messaging team how redelivery and acknowledgement are configured on the queue. Make the start-or-correlate decision explicit: use a start event when the message introduces a new business object, and correlate when the business object already exists, and validate both paths with replayed messages in a test environment before go-live.
Mapping RabbitMQ message fields to Flowable event payloads and variables
This table maps each RabbitMQ message attribute to the Flowable event element it feeds, such as payload fields, correlation parameters or process variables. Read it as a contract checklist: the right-hand column names what the messaging team and the process team must agree on before the channel goes live. The main takeaway is that the routing key, message ID and body schema need explicit ownership, because correlation and retries depend on them.
| Message attribute | Flowable target | Agree with the messaging team |
|---|---|---|
| Routing key | Channel routing, selects the event definition for inbound messages | Naming scheme, whether one queue carries several event types, and who owns binding changes |
| Message body fields | Event payload fields declared in the event definition | Field names, data types, required versus optional fields, and units for amounts and dates |
| Correlation field in body | Correlation parameter that matches the message to a running instance | Which business key is stable across systems, and whether it is unique per instance |
| Message ID | Idempotency key recorded for duplicate detection in your application | Whether the producer sets a unique ID on every message and how redeliveries reuse it |
| Headers (custom) | Optional mapping to process variables, such as tenant or source system | Which header names are reserved, and whether headers are trusted input or only informational |
| Schema version field | Used to choose the matching event definition version during routing | How breaking changes are versioned, the deprecation window, and who approves a new version |
| Timestamp | Mapped to a process variable for timers, audit and history | Time zone and format (for example, ISO 8601 in UTC), and whether producer or broker time is authoritative |
| Content type and encoding | Determines how the payload is parsed before field mapping | JSON or another format, character encoding, and maximum message size |
Securing the RabbitMQ connection and Flowable endpoints
Flowable's event registry opens two paths into your process engine: the RabbitMQ connection it uses to send and receive messages, and the REST endpoints that expose events and instances. Each path needs its own credentials, network protection and data handling rules, agreed with the messaging team before the first channel goes live.
Broker credentials and vhost permissions
Give the Flowable consumer and publisher separate RabbitMQ users, each limited to the virtual host that carries its channels. Permissions for configure, write and read should cover only the exchanges and queues named in the channel definitions, so a compromised process application cannot reach unrelated traffic. Ask your broker administrators to confirm the permission model and how credentials are rotated, since these settings live in RabbitMQ rather than in Flowable.
TLS on the broker connection
Messages carry business data and identifiers, so the connection between the Flowable engine and the RabbitMQ broker should use TLS and should not accept plaintext listeners from application networks. Confirm with your broker team which listener ports, certificate authority and client certificate options are available, and how the Flowable connection settings reference the truststore. Test that the engine fails to connect when the certificate is wrong, rather than silently falling back.
Least-privilege queue bindings
Bind each inbound channel to its own queue and routing key, and avoid shared catch-all queues that deliver messages meant for other applications to the process engine. Outbound channels should publish only to the exchanges their send event tasks need. Review bindings whenever a model adds a channel, because the event registry configuration is the place where a new destination quietly widens what the engine can read or write.
REST endpoints that expose events
The Flowable REST application and any custom controllers that accept events over HTTP need authentication and authorization before they reach the event registry. Basic authentication with default or shared accounts is not a suitable production setting. Check which endpoints can deploy event definitions, start instances or trigger correlation, and restrict each to the callers that own that action. The Flowable security documentation sets out what the engine leaves to your application.
Sensitive payload data in variables and logs
Event payloads become process variables and can appear in history, job logs and error messages. Decide which fields are business data that must be stored, which are sensitive and should be dropped or referenced by ID, and which should never be mapped at all. Confirm with your security and privacy teams how long history is kept and who can query it. Turn on logging at a level that records event names and correlation keys without writing full message bodies.
Access to engine data and history
Users who can read process variables through the Flowable APIs can see everything the events carried, so the access model for running instances should match the sensitivity of the messages. Map candidate groups and privileges to the roles your organization already uses, and keep the IDM identity service aligned with the directory you trust. Document who may replay or re-send a message, because a replayed event can start a second instance or trigger a boundary event on a live one.
Common RabbitMQ integration failures in Flowable and how to fix them
This table lists the failures teams most often hit when RabbitMQ messages drive Flowable processes and cases, with the likely cause and the first check for each. Read it as a triage order: confirm the message reached the queue, then the channel binding, then the event definition and correlation values.
| Failure | Likely cause | First check |
|---|---|---|
| Message matches no instance | Correlation parameter value in the payload does not equal the value stored on the running instance, or the wrong field name is mapped | Compare the correlation value in the raw message with the business key or variable on the waiting instance, and check the field name in the event definition |
| Duplicate process starts | Broker redelivers a message after a consumer failure or timeout, and the inbound channel starts a new instance each time | Check whether the message ID or a business identifier is used to deduplicate, and review consumer acknowledgment behavior in the RabbitMQ management view |
| Unbound queue receives nothing | The queue exists but no binding connects the exchange and routing key that the channel definition expects, or the names differ by environment | Compare the exchange, routing key and queue names in RabbitMQ with the channel definition in the target environment |
| Payload fields missing at runtime | The event definition does not declare a field that the sender includes, or the sender omits a field the definition marks as required | Diff the JSON published by the sender against the payload fields declared in the event definition |
| Messages stuck unacknowledged | The consumer receives the message but fails before the engine completes the trigger, so the message is not acknowledged and stays in flight | Check Flowable logs for exceptions around the event handling and confirm the unacknowledged count in the queue view |
| Certificate or credential errors | Broker user, password, vhost permissions or TLS trust store for the Flowable connection differ from what the broker expects | Test the same credentials and certificate chain outside Flowable, then compare the connection settings used by the engine in each environment |
| Outbound events never leave the engine | Send event task points to a channel with no reachable broker address, or the exchange lacks write permission for that user | Confirm the channel definition targets the intended exchange and that the Flowable user can publish to it |
| Events arrive after the instance moved on | The process is no longer waiting at the expected catch point, so the correlated event has no matching subscription | Check the current activity of the instance and confirm the boundary or catch event is active at the time the message arrives |
When RabbitMQ is a better broker choice than Kafka or JMS for process events
Choose RabbitMQ when the process events behave like work to be handed out and acknowledged, and Kafka or JMS when your existing estate or replay needs point elsewhere. RabbitMQ fits well when messages are commands or task-like events that one consumer should take, route by routing key and then discard once handled, which matches how a Flowable event registry channel typically starts a process or triggers a boundary event. Kafka is a different model: it keeps an ordered log that consumers read by offset, so replay and multiple independent readers are natural. The Kafka upgrade notes also set operational prerequisites you must budget for: brokers require Java 17 since Kafka 4.0, and KRaft is the only supported mode, so ZooKeeper-based clusters must migrate before upgrading to 4.x. Confirm which Kafka release line you would run against the supported releases on the Apache Kafka downloads page.
JMS is usually the right answer when your organization already runs an enterprise messaging platform with established queues, topics, security policies, monitoring and support contracts. Flowable's event registry supports JMS out of the box, so the integration cost is mostly in channel definitions and agreeing message formats with the messaging team, not in a new broker. Adding RabbitMQ next to an existing JMS estate usually means a second platform to operate, so it needs a clear reason. The decision therefore turns on three things you must confirm before you pick: what messaging platforms and skills your operations team already has, whether any consumer must re-read past process events (which favors Kafka's log model), and whether message ordering and per-message routing rules are the main requirement (which favors RabbitMQ). Ask your messaging team for their support model, retention expectations and security baseline, and test the chosen broker against your correlation parameters before committing.
Questions teams ask before connecting Flowable to RabbitMQ
How much effort does a Flowable and RabbitMQ integration take?
Effort depends mostly on how many event types the models must handle, how hard correlation is, and who owns the broker. A small set of inbound events that start one process is a contained build. Many event types, each routed to a running instance by several correlation parameters, adds design, testing and failure-case work. Each event needs a definition with its payload fields, a channel definition that binds it to a RabbitMQ destination, and a test that proves the right instance receives it. Ask any partner to list event types, correlation keys and the broker topology before quoting, because those three inputs move the effort more than anything else.
Can an in-house team connect Flowable to RabbitMQ on its own?
A team with Java and Flowable experience can usually build a first inbound channel without outside help, since the event registry is configured through event and channel definitions and the engine is embedded or reached over its REST API. The harder parts are the ones teams underestimate: idempotent handling of redelivered messages, correlation when a message arrives before the instance is waiting for it, dead-letter handling, and monitoring. Check whether your engineers have built these before. If they have not, a short design review or a fixed-scope build with a knowledge transfer step may cost less than learning on a production route.
What does the messaging team need to provide for the integration?
The messaging team owns the broker, so the integration needs their agreement on several points before build starts:
How does DeployOpen scope a Flowable and RabbitMQ integration in writing?
DeployOpen works from a written scope agreed before work starts. For this integration, that scope normally lists the event types and direction of each flow, the correlation parameters per event, the channel definitions and RabbitMQ destinations involved, the process and case models that change, the test cases and the environments where they run, and the handover material. Deliverables and timelines are fixed in that document. Ongoing support, upgrades and continuous testing can be added as a retainer. DeployOpen does not publish a price list, so a quote follows from the scope, and you should ask for it to show each event type as a separate line.
When should a team choose Kafka or JMS instead of RabbitMQ for process events?
Choose RabbitMQ when your organization already runs it, when events are work requests that should be consumed once, and when routing rules and per-message acknowledgement fit the flow. Consider Kafka when you need a durable, replayable event log that several independent consumers read at their own pace, and be ready to operate it. Kafka is an Apache Software Foundation project under the Apache License 2.0, and its KRaft mode is the only option in 4.0 and later. Choose JMS when your estate already runs a JMS provider and the messaging team supports it. The Flowable event registry supports all three, so the choice is mostly about the broker you can operate well.
What goes wrong most often when Flowable consumes RabbitMQ messages?
Teams most often hit problems with redelivery, correlation and version drift. A message redelivered after a timeout can start a second process instance if the start event is not guarded, so the inbound design needs a deduplication key. A message can arrive before the process reaches the waiting point, which a design must handle explicitly. Payload changes made by a publisher can break event definitions without any error at deploy time. Test each of these with replayed messages in a staging environment, and agree on a schema change process with the publishing team before go-live.
Does the Flowable event registry require a specific RabbitMQ setup?
The Flowable event registry supports RabbitMQ out of the box and sends and receives events through channel definitions that bind an event to a broker destination. What the setup needs depends on your queue layout, your RabbitMQ version and your security policy, so confirm those details with the messaging team and in the Flowable event registry documentation before you design the channels. Ask for the exact destination names, durability settings and credentials handling in writing so that the test and production environments match.
Testing and operating the event integration after go-live
Start the test plan with the four message paths that can fail in production: a message that starts a process, a message that correlates to a running instance, a duplicate message, and a message that does not match any definition or payload. For each path, write the expected result before testing. A start message should create exactly one process instance with the payload fields mapped into process variables. A correlating message should reach the single waiting instance identified by the correlation parameters defined in the event definition, and nothing else. A duplicate should be rejected or ignored in a way your process design expects, which means you must decide whether the model tolerates a second start or whether the channel or the sender must deduplicate. An invalid message should be routed to a dead-letter queue on the RabbitMQ side, not silently dropped by the engine. Run these cases against a broker and a database that match production, because queue settings and acknowledgment behavior are where differences tend to show up.
Verify outbound events by checking the message that arrives on the broker, not only the fact that a send event task completed in the engine. Compare the routing key, payload fields and headers with the channel definition and the consuming team's contract. For monitoring, use the Flowable actuator endpoint at /actuator/flowable if you run the Spring Boot starters, and combine it with engine logs and job queues for failed or retrying jobs. Confirm in your own environment which metrics the endpoint exposes for your Flowable version, and alert on growth in failed jobs and on messages that stop being acknowledged, since the engine cannot see a stuck queue on its own.
Agree the ownership split before go-live. The platform team usually owns the event and channel definitions, the deployment pipeline that ships them, and the engine configuration. The messaging team usually owns exchanges, queues, bindings, dead-letter policies and broker credentials. Any change that alters a payload field, correlation parameter or routing key needs both teams to approve it and to test it in a non-production environment first. Write this split into a change procedure with named roles, and check the current broker documentation for the queue and acknowledgment features you rely on, since those settings are owned outside Flowable.
How DeployOpen scopes and delivers Flowable and RabbitMQ integrations
DeployOpen plans, builds, documents and supports Flowable and RabbitMQ integration with the event registry inside infrastructure you control. Work starts from a written scope that names the event and channel definitions, correlation parameters and broker settings, so your messaging and process teams agree on the contract before anything is built.
How we scope
- We list each inbound and outbound event, its payload fields and the process or case it starts or reaches.
- We agree correlation parameters with your messaging team so each RabbitMQ message maps to one running instance.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work begins.
How we build
- We define event and channel definitions in the Flowable event registry and bind them to your RabbitMQ exchanges and queues.
- We wire start events, boundary triggers and send event tasks into your BPMN and CMMN models with tested delegates.
- We test message redelivery, duplicate handling and unmatched correlation so failure paths are verified before go-live.
How we hand over
- We document the event contract, channel bindings, broker settings and correlation rules in a form your team can maintain.
- We record the test cases and results so your team can repeat them after later changes.
- We walk your platform and operations engineers through monitoring, failed jobs and how to add a new event.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- We can plan Flowable version upgrades and check that event registry integrations still behave as documented.
- Confirm with us which RabbitMQ version and client libraries your environment standardizes on before scoping.
