How Flowable JMS integration with the event registry works
A Java team with JMS queues and topics that must start or advance Flowable processes and cases needs to know how the event registry connects those destinations to the engine. The event registry uses a channel definition to describe the JMS destination and an event definition to describe the payload the engine expects, and correlation parameters decide which running instance receives each inbound message. The Flowable docs define this pattern in their event registry introduction, and the starting example there is a process instance created from a JMS queue message.
Inbound channels carry messages from JMS into Flowable. An inbound channel can start a new process instance when a message arrives, or it can match a message to an existing event subscription, such as a boundary event waiting on a process or case. Outbound channels run the other way: a send event task in a model publishes an event to a JMS destination. Correlation parameter values are what tie an incoming event to the subscription of one specific case or process instance, so the payload fields chosen for correlation must be present, stable and unique for that business key in every message the sender produces.
Before build starts, confirm with the messaging team which destinations are queues and which are topics, how consumers are grouped, whether redelivery and dead-letter behavior is defined, and which message fields identify the business entity. Confirm also the JMS provider and version your organization runs, because the channel configuration depends on how the destination is addressed. Agree on the payload format and schema ownership early, since a change to a field used for correlation will silently stop messages from reaching their instances.
What you need before connecting Flowable to JMS
A JMS integration touches four teams at once: the engine team, the messaging team, the network team and the database owners. Agree on the engine version, the broker and its client library, the transport security and the subscription storage before any channel definition is written, because each choice constrains the rest.
Flowable engine version and baseline
Pick the Flowable release first, since its Java, Spring Boot and Jakarta baseline decides which JMS client libraries and Spring integration packages you can use. Flowable 8.0.0 moved to Spring Framework 7 and Spring Boot 4 and dropped Spring Boot 3 compatibility, while Flowable 7.0.0 required Java 17, Spring Boot 3 and Jakarta EE. Check which line your platform team already runs before choosing the broker client. Confirm the Java runtime with Flowable's current release notes.
Broker version and JMS client library
No broker version is fixed for this integration, so ask the messaging team which JMS provider, version and client library they already operate. Confirm with the broker vendor that the client supports the Jakarta Messaging API your Flowable line uses, and that the broker's destination types match your design. Do not assume a library compatible with one Flowable line also works with the other.
Destination naming and ownership
Agree on the queue and topic names, who creates them, and which team owns the dead-letter destination. Event channel definitions point at these destinations, so a renamed queue breaks process starts silently unless the change goes through the same review as the model. Record the owner of each destination in the design document.
Network paths and TLS
Map every connection from the Flowable nodes to the broker, including failover addresses and any cross-zone or cross-site routes. Decide whether the broker requires TLS and mutual authentication, and who issues and rotates the certificates. Firewall rules must allow the engine nodes, not only one host, because the async executor can run on any node.
Credentials and secret storage
Decide how the engine authenticates to the broker and where those credentials live. Avoid placing broker passwords in model files or process variables, and confirm that the secret store your platform uses can inject them into each engine node. Ask the messaging team for a dedicated service account with only the send and receive rights the channels need.
Database holding event subscriptions
Event subscriptions for correlation are stored in the Flowable database, so confirm the supported database type, its version and backup schedule with the database owners. Flowable supports H2, MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server, and MySQL below 5.6.4 lacks millisecond precision. Check that the schema upgrade path is covered before the first deployment.
Configuring the JMS channel and event definitions step by step
This sequence takes a JMS destination from an agreed name and message format to a deployed Flowable event registry setup that starts or correlates process instances and publishes outbound events. Each step closes with a check that the wiring works before the next one begins.
Agree destination names and message format
Before any Flowable configuration, the process owners, the messaging team and the Flowable engineers agree on the JMS queue or topic names for each inbound and outbound flow, the message body format (for example JSON or XML), the header properties that carry identifiers, and which system owns each destination in every environment. Write these down as a short interface agreement. The step is done when both teams have signed off the destination names and a sample message that the messaging team can produce on a non-production broker.
Define the inbound channel for the JMS destination
Create a channel definition that points at the agreed inbound JMS destination and identifies it as an inbound channel. The Flowable event registry docs use a JMS queue message that starts a process as the reference pattern, so model your channel the same way. Keep the channel key and destination name in configuration rather than hard-coding them in the model, so the same model can run against different brokers. The check is that the channel appears in the deployed event registry after deployment, with no deployment errors in the engine log.
Define the event payload structure
Create an event definition that describes the payload the channel will receive. List each field the process needs, its type and whether it is required, and mark which fields serve as correlation values. Agree this structure with the messaging team, because a field renamed on the producer side will silently break matching on the Flowable side. The check is that the event definition deploys and that a test message with all required fields maps to the expected event properties when you inspect a sample event in a non-production environment.
Deploy the channel and event definitions together
Package the channel and event definitions with the process and case models that use them, and deploy them through the same pipeline you use for process definitions. Deploying the event definitions with the models that reference them avoids a window where a model subscribes to an event that does not exist. Confirm the deployment version recorded for each definition in the engine, because later changes to payload structure or destination names will need a new version rather than an in-place edit. The check is that the deployed definitions are listed with the expected keys and versions.
Bind the start or boundary event to the event definition
In the BPMN model, attach an event-driven start event or an event-based boundary event to the event definition, depending on whether the message should start a new process instance or interrupt a running activity. Use the event registry extensions your model editor supports and verify the exact element configuration against the Flowable docs for your engine version. The check is that deploying the model creates an event subscription for each bound event, which you can confirm by querying the event subscriptions for the deployed definition.
Configure correlation parameters
Map one or more correlation parameters from the event payload to process or case variables, so each incoming message reaches the subscription of the correct running instance. Choose a business key or identifier that is unique for the instance lifetime, and document what happens when a message arrives with no matching instance or with duplicate keys. For a start event, the correlation values become variables on the new instance. The check is that sending a test message with a known identifier triggers the waiting subscription for that instance only, and that a message with an unknown identifier is handled as your design specifies.
Add the outbound channel for send event tasks
Define an outbound channel that points at the JMS destination the messaging team will consume, then add a send event task in the model that references the outbound event definition. Agree the outbound message format and any headers the consumer needs for routing or deduplication. The check is that running a test instance through the send event task publishes one message to the non-production destination, and the consumer receives the payload with the expected fields.
Test end to end on a non-production destination
Run the full path on a non-production broker: send inbound test messages with valid, missing and duplicate correlation values, confirm process starts and boundary triggers, and confirm the outbound message arrives with the expected content. Include a message the engine cannot map, so you can see how the failure surfaces to operators. Record the results and the event subscription state before and after each test. The sequence is complete when every test case behaves as the interface agreement says, and the messaging team has checked the outbound messages on their side.
How correlation parameters route messages to the right instance
Correlation parameter values decide which running case or process instance receives a JMS message. The event registry matches an incoming event against the event subscriptions that exist at that moment, so the values you define in the channel and event model must be present in every message and must equal the values the subscription was created with. Before the build starts, ask the messaging team which fields in the message body or headers carry the business identifier, and confirm with them that producers populate those fields on every send, including retries and replays. Treat the correlation design as a contract between the two teams, not as a detail the Flowable developers settle alone.
Choose correlation keys that are stable for the life of the work and unique within the scope you match on. An order number that is reused after a cancellation, or a customer identifier that many open cases share, will route one message to several instances or to the wrong one. Ask the business owners which identifier is unique per instance, and ask the messaging team whether that identifier changes when a record is corrected. Where no single identifier is unique, agree on a composite key and decide who generates it, because a key minted by the producer is easier to keep stable than one derived later by the engine. Start-event messages and messages that trigger boundary events on running work need different handling. A start event creates a new instance, so its correlation values usually identify the new work and must not collide with an open instance that should absorb the message instead. A message aimed at a boundary event must find an existing subscription, so the process design must decide what happens when the instance has already moved past that point.
Plan the path for messages that match nothing or match the wrong instance before go-live. A message with no matching subscription can arrive early, after the subscription has ended, or from a producer with a mismatched key. Decide with the messaging team whether these go to a dead-letter destination, a holding queue, or an operations queue that someone reviews, and who owns each choice. Test the mismatch cases explicitly, including duplicate deliveries of the same message, because JMS delivery guarantees depend on how the broker and consumers are configured. Confirm the exact behavior of unmatched events with the version of Flowable you deploy by checking the Flowable event registry introduction and running negative tests against your own models.
Mapping JMS message fields to Flowable event and process data
This table maps each part of a JMS message, from destination name to headers, properties and body fields, to the Flowable element it populates. Read it as a contract draft: each row names who owns the source and what the messaging team must confirm before channel and event definitions are built. The main takeaway is that correlation keys and schema versions need agreed owners, or events will match the wrong instance or fail silently.
| Source | Flowable element | Owner | What to confirm with the messaging team |
|---|---|---|---|
| JMS destination name (queue or topic) | Channel definition destination and its type | Messaging team | Exact queue or topic name per environment, and whether the destination is a queue or a topic |
| JMS message body fields | Event definition payload attributes | Producing application team | Message format (for example JSON or XML), field names, data types and which fields are mandatory |
| Schema version field or JMS property | Event definition version selection in the model | Producing application team | How schema versions are signaled, how long old versions stay in circulation and who approves a change |
| JMS correlation ID header | Correlation parameter that matches an event to a running instance | Messaging team with the process owner | Whether the producer sets it, its uniqueness scope and whether redelivered messages keep the same value |
| Custom JMS properties (business keys such as order or case reference) | Correlation parameters and event payload values | Producing application team | Property names, value formats, and whether the business key is unique across the events that can start or trigger an instance |
| Message payload values copied into process variables | Process variables set by the event mapping on start or trigger | Process owner | Which fields become variables, their types, and whether sensitive fields may be stored in process history |
| JMS redelivery and duplicate delivery | Idempotency handling at the instance level | Messaging team and process owner | Redelivery settings, whether the broker can deliver the same message twice, and how duplicates should be detected |
Inbound and outbound channels compared
Inbound channels read messages from a JMS queue or topic and pass them to the event registry. A message can start a new process instance or match a running instance so that a boundary event fires on a waiting task. The channel definition names the JMS destination, and the event definition describes the payload fields the engine reads. Correlation parameters decide which running instance receives an event, so the design of those keys matters as much as the destination itself.
- Destination and type: Agree whether each source is a queue, where one consumer takes each message, or a topic, where each subscriber gets a copy. Record the destination names for every environment.
- Payload contract: Fix the message schema, field names, types and a version field with the producer, so the event definition stays stable when the producer changes.
- Correlation keys: Name the business identifier that every message carries and the engine uses to find the instance. Confirm what the engine does with messages that lack the key.
- Start versus boundary: Decide which message types create instances and which only fire boundary events on waiting tasks. Confirm what happens when no subscription matches.
- Consumer account and selectors: Ask the messaging team who provisions the consumer account, which selector rules apply and which acknowledgement mode is used.
Before the channel reaches a shared environment, check that a sample message from the producer matches the event definition field by field. The Flowable event registry introduction explains how channel and event definitions fit together.
Outbound channels publish events from a running model through a send event task. The model maps process variables into a payload and sends it to a JMS destination, where other systems consume it. The messaging team takes on ownership of the destination and the consumer side, while the process team owns what the model sends and when. Most outbound problems start with unclear answers to who consumes the message and what that consumer expects.
- Destination ownership: Agree which team creates and names the topic or queue, who sets its retention and access rules, and who receives alerts when it backs up.
- Payload mapping: Define exactly which process variables leave the engine. Keep personal or regulated data out of payloads unless the consumer is approved to receive it.
- Delivery expectations: Plan for duplicate delivery and make consumers idempotent. Confirm the broker's delivery guarantees and how the send task retries after a failed publish.
- Ordering: Messages from separate instances can arrive in any order. Document which consumers depend on order and how they handle an event that arrives early.
- Broker outage behavior: Ask what the send task does when the broker is unreachable, whether the step is retried, and whether the failure stops the process or leaves a failed job for an operator.
For each outbound event, write down the consumer, the schema version and the expected volume, then confirm those values with the messaging team before the model is deployed.
Inbound and outbound failures show up in different places. An inbound failure can leave a message unread on the broker, drop it at the consumer or leave it unmatched inside the engine. An outbound failure appears in the process, as a failed step or job that an operator has to inspect. The test plan should cover both directions with the same set of cases, run against a broker that matches the production product and configuration as closely as the team can arrange.
- Malformed payloads: Send messages with missing or mistyped fields. Agree with the messaging team on a dead-letter destination and confirm where the engine logs the rejected event.
- Unmatched correlation: Send an event before its instance reaches the waiting point, then after it. Confirm whether the engine buffers the event, discards it or reports it.
- Duplicate delivery: Deliver the same message twice and check that no second instance starts and no side effect repeats.
- Broker restart: Stop the broker during a test run, restart it and confirm that messages resume and nothing is lost or doubled. Record how long recovery takes in your environment.
- Shared monitoring: Track message counts at the producer, the broker and the engine, and set alerts on failed jobs so both teams see the same numbers.
Run this suite again after every change to a channel, event definition or broker configuration, because a small schema change can break correlation without any visible error.
Securing the JMS path between broker and Flowable
The JMS path has three parties: the broker, the Flowable event registry channel, and the process or case models that receive or send messages. Each card below covers one control that must be agreed between your messaging and Flowable teams before channels go live. Confirm every broker-specific option with your broker vendor, since the Flowable docs describe the channel and event model but not each broker's security settings.
Broker credentials outside the model
Store the JMS connection username and password in your secrets manager or the deployment environment, never in the channel definition, BPMN or CMMN model, or deployed artifact. Models are copied between environments and kept in version control, so a credential inside one spreads to every copy. Ask the messaging team which service account the engine uses, whether it rotates, and how a rotation reaches running Flowable nodes without a redeploy.
**TLS on the broker connection**
Require encrypted transport between the Flowable nodes and the broker, and confirm the trust store that the JVM uses to validate the broker certificate. A plain connection exposes message payloads and credentials to anyone on the network path. Ask the broker vendor which TLS versions and cipher settings it supports, and how the JMS client configuration in your Spring or servlet deployment enables them.
Least-privilege destination access
Grant the engine's broker account send or receive rights only on the queues and topics named in its channel definitions, and nothing else. A channel that reads one queue should not be able to browse or publish to administrative or other business destinations. Review the list of destinations against the channel inventory each time a new channel is added, and ask the messaging team to confirm that wildcard permissions are not granted.
Personal data in message content
Identify which inbound payloads carry personal data, such as names, account numbers or health details, before agreeing on the message format. Decide whether the sender can omit those fields, send an identifier that the process looks up later, or encrypt the field end to end. Confirm with your privacy and compliance leads where broker retention, dead-letter queues and message logs keep those payloads, and for how long.
Sensitive values in variables and logs
Process variables are persisted in the engine database and often appear in history and audit data, so a card number or token copied into a variable stays there. Map only the fields a task needs, and keep secrets out of logs by reviewing logging levels for the JMS listener and the engine packages. Ask your Flowable developers which payload fields become variables and whether any are excluded from history.
Common JMS integration failures and how to fix them
This table lists the failures teams most often hit when JMS messages drive Flowable event registry channels and outbound events. Each row gives the likely cause and the fix, so the engineers and the messaging team can check the same points before go-live.
| Failure | Likely cause | Fix |
|---|---|---|
| Message arrives with no matching correlation | The correlation parameter in the event definition does not map to a value present in the payload, or the running instance was never subscribed on that key. | Confirm each correlation parameter name and type with the messaging team, check the sample payload against the event definition, and test with a message for a known running instance. |
| Duplicate instances from redelivered messages | JMS redelivers a message after a consumer failure or acknowledgment timeout, and the channel starts a new process each time. | Agree on an idempotency key in the payload, use it as a correlation value, and decide whether a repeat should start a new instance or update the existing one. |
| Channel points at the wrong destination | The channel definition names a queue or topic that differs from the one the producer publishes to, or uses the wrong destination type. | Compare the destination name and type (queue or topic) in the channel definition with the broker configuration, and confirm the producer's destination in a test environment. |
| Payload does not match the event definition | The producer changed field names, types or nesting, or sends a different format than the event definition expects. | Version the event definition with the producer's schema, add a contract test on both sides, and reject or log malformed messages instead of letting them fail silently. |
| Outbound messages fail when the broker is unreachable | A send event task calls the broker during the process transaction, and a network outage or broker restart causes the send to fail. | Confirm with the messaging team how the send retries and what happens to the process step, and plan monitoring for failed outbound sends and their retry state. |
| Messages consumed but instance does not advance | The event matches a subscription that is no longer active, such as a boundary event on a task that already completed. | Review the process model for the timing of the boundary event, and confirm in testing which states can receive the event. |
| Broker credentials or connection rejected after deployment | Credentials, TLS settings or connection factory values differ between test and production configuration. | Keep broker connection settings in environment-specific configuration managed by your platform team, and verify connectivity as part of the deployment checklist. |
Questions buyers ask about Flowable JMS integration
What drives the cost of a Flowable JMS integration, and who pays for what?
The cost depends on how many inbound and outbound channels exist, how much correlation logic each message needs, how many messaging decisions remain open, and how much testing the broker environment requires. Flowable's open source engines are licensed under Apache 2.0, so the engine itself carries no license fee. You pay for the work around it: designing channel and event definitions, writing the application code that reads and sends messages, configuring the broker connection, testing, and handover. Some of this is one-time (design, build, test), and some recurs (broker operations, monitoring, and changes when new message types appear). Ask any quote to split these items, name who owns the broker, and state which messaging decisions are assumed to be made before the build starts.
Can an internal team build a Flowable JMS integration without a partner?
Yes, if the team already knows Java, Spring or the Flowable engine, and has someone who can run JMS in production. The Flowable event registry documents JMS as a channel type, and the example of starting a process instance from a JMS queue message shows the pattern: a channel definition for the destination and an event definition for the payload. The harder parts are usually not the XML or the configuration. They are agreeing message contracts, handling duplicates and redelivery, and testing against a real broker. A partner is most useful when the team has no experience with the event registry, when many channels must be delivered in a fixed window, or when the integration must be reviewed against your compliance requirements. Confirm your team's skills against the scope before deciding.
How long does the work take, and what changes the timeline?
The timeline depends mainly on the number of channels, the number of event types each channel carries, and how many messaging decisions are still open. A single inbound queue that starts one process is a small piece of work. Several topics that start processes, trigger boundary events on running instances, and publish outbound events from send event tasks take longer, because each needs a correlation rule, a payload contract and tests. Open questions about message format, broker access, dead-letter handling and environment promotion add time when they surface during the build instead of before it. Ask for a timeline that lists each channel, the decisions it depends on, and the dates the messaging team must confirm them. No duration is given here because none has been supplied for this topic.
What does the integration need from the messaging team and the platform owners?
The integration needs decisions and access from two groups before development starts. The messaging team should confirm:
- The queues and topics the engine will read from or publish to, and their naming
- The message format, schema versioning and which fields carry correlation values
- Redelivery, dead-letter and acknowledgement behavior, and how poison messages are handled
- Authentication, network paths and credential rotation for the broker
The platform owners should confirm the database that the Flowable engine uses, the cluster or hosts where the engine runs, how configuration is promoted between environments, and where logs and monitoring for failed jobs go. Ask any quote to list these dependencies and who is responsible for each one.
Does the Flowable open source license cover support, and how does the community forum fit in?
Flowable open source is licensed under Apache 2.0, so you can use, modify and deploy the engines without a license fee. The open source offering includes a community forum for questions. Flowable's commercial products, such as Flowable Work, Engage, Orchestrate and Design, are built on the same engines and add low-code modeling, visual debugging, security controls, monitoring and governance. Professional services and partners are offered separately from the open source project. Community forum answers are not a service agreement with response times. If you need guaranteed response, an agreed support scope or someone accountable for production incidents, that is a separate arrangement to put in writing. DeployOpen's own support is available as a retainer and is scoped in writing, not assumed by the license.
What are the main risks of driving Flowable from JMS, and how are they checked?
The main risks are duplicate delivery, messages that arrive before the process they target exists, correlation values that match the wrong instance, and broker outages that leave messages unprocessed. Each one should be tested with the real broker, not only with mocks. Check that a repeated message does not start a second instance or trigger a boundary event twice, that a message with no matching subscription is handled deliberately, and that correlation parameters are unique for the business key you choose. Also test what happens when the Flowable node restarts during processing. Record the test cases in the handover so operations can repeat them after upgrades.
Does the integration change how audit and security evidence is produced?
It can. Inbound messages that start processes or move cases become part of the process history, so the message payload, the correlation value and the resulting instance should be traceable. Decide early which payload fields are stored as process variables, because those fields persist in history and may include personal data. Restrict who can publish to the queues and topics, and use authenticated broker connections. Flowable's security documentation covers the engine and APIs, but broker access control sits with the messaging team. A compliance assessment would ask for evidence of these controls. DeployOpen prepares the systems and evidence for such assessments, but independent auditors issue any audit report or certification.
What to agree with the messaging team before build starts
Most JMS integration problems in a Flowable build are not engine problems. They come from decisions the messaging team and the process team never made together, so agree these before the event and channel definitions are written. Start with destination ownership and naming: who creates the JMS queues and topics, who owns their names in each environment, and who approves a change to a destination that a channel definition points at. Ask for the exact destination names, whether they are queues or topics, and which application identity Flowable will use to connect. Write these into the scope so a renamed queue does not silently stop a process from starting.
Next, agree the message schema and its versioning. The event definition describes the payload Flowable expects, so the messaging team must commit to a format, a field list and a rule for adding or removing fields. Decide how a breaking change is announced, how old and new payloads coexist during a rollout, and which field carries the correlation parameter values that match an event to a running instance. A missing correlation field usually means a message is accepted but never reaches its subscription, so ask who checks payloads against the definition before go-live.
Then settle delivery semantics and duplicate handling. JMS brokers can redeliver a message, and the team must decide whether a duplicate start of a process is acceptable, whether a message ID or business key is used to ignore repeats, and what happens when a boundary event fires twice on one instance. Agree the broker-side dead-letter and retry policy too: how many redeliveries happen before a message is parked, who inspects parked messages, and whether replay is allowed. Finally, agree environment separation and alerting: separate brokers or destinations for test, staging and production, and a named on-call group that receives alerts when a channel stops consuming, with the time window that counts as stopped. Record all of this in the statement of work before build starts.
How DeployOpen scopes and delivers Flowable JMS integrations
DeployOpen plans, builds, documents and supports Flowable JMS integration with the event registry inside your own infrastructure. We start from the queues, topics, message formats and correlation keys your messaging team already runs, then agree the event and channel design before any model is changed.
How we scope
- The written scope lists each JMS destination, its direction, and which process or case it starts or reaches.
- Scope records the message schema, correlation parameters and the expected handling of duplicate or late messages.
- Engagements are fixed-scope, so deliverables and timelines are agreed in writing before build work starts.
How we build
- We define channel and event definitions, then wire inbound listeners and outbound send event tasks to the agreed destinations.
- Each correlation rule is tested against running instances, including messages that match none or several subscriptions.
- Integration tests run against a JMS broker in a non-production environment that mirrors your broker configuration.
How we hand over
- Handover includes the channel and event definitions, configuration, test cases and the messaging contract as written documentation.
- Runbooks describe how to inspect failed deliveries, replay messages and check which instances a message reached.
- Your engineers receive a walkthrough of the design decisions so they can extend the integration after handover.
How we support
- Ongoing support, upgrades and continuous testing for the integration are available as a retainer.
- Support covers broker version changes, Flowable upgrades and schema changes in the messages your producers send.
- Confirm with us during scoping which support level and response expectations apply to your environment.
