How a Flowable business rule task calls a DMN decision table
A process needs rules to decide where work goes next, such as which approver to assign, whether a case needs manual review, or which price tier applies. Those rules usually change more often than the process around them. The business rule task in a Flowable BPMN process is the element that lets the process call a deployed DMN decision table by its key, pass process variables in as inputs, and receive the decision result back as variables the rest of the process can read. The process model then stays focused on steps and handoffs, while the rule logic lives in a decision table that can be maintained on its own schedule. Confirm the exact configuration properties for the task in the Flowable BPMN documentation for your engine version before you write the first model.
Use the business rule task when the logic is a set of conditions over inputs that the business owns and expects to revise, and when reviewers need to read the rules as a table. Hard-coding the same logic in exclusive gateway conditions or in Java delegates works for a few stable branches, but every change then requires editing the process or the code and redeploying it. Gateways are still the right tool for control flow that is structural and does not change, such as whether a required document was uploaded. A delegate is the right tool when the logic calls external systems or needs code that a table cannot express. Many teams end up with a mix, and the decision to make is which layer each rule belongs in.
Before the first release, agree with the business owners which process variables feed the decision and which result variables the process will branch on. Those names become a contract between the two teams. Changing a variable name in the process can silently break a decision that still runs, so review the mapping whenever either side changes. Also decide how the process will behave when no rule matches, because an unmatched input is a routing question for the process, not just a technical error. Validate both paths with test data before go-live, and record which decision version each running instance used so that a later rule change can be explained during an audit.
Which integration pattern fits which rule change pattern
This table compares three ways to connect rules to a process: the DMN engine embedded in the same application, decisions called through the Flowable REST application, and hard-coded gateway conditions or delegates. Read each row against how often your rules change and who changes them. The main takeaway is that the more often business owners change rules without a code release, the more the decision logic should sit in a deployed decision table rather than in process XML or Java.
| Pattern | When it fits | How rule changes reach running processes | What the team must test |
|---|---|---|---|
| Embedded DMN engine in the same application | Rules change with the application release, and one team owns both the process and the decision table | Changes arrive when a new decision version is deployed alongside the application, and the team confirms which version new instances start with | Business rule task input mapping, the output variables read by gateways, and behavior after a redeploy with instances still in flight |
| Decisions called through the Flowable REST application | Several applications or teams need the same decisions, or the rule owner deploys decisions separately from the processes | Newly deployed decision versions apply to calls made after deployment, so the team checks which version a given caller receives | Authentication on the decision endpoints, request payload shape, error handling when a decision key is missing, and version selection across callers |
| Hard-coded gateway conditions | Rules are few, stable and tied closely to the process path, such as a single yes or no check | Each change needs a new process definition version and a release, and running instances keep the version they started with unless migrated | Every branch of the gateway, default flows, and the effect of a changed condition on instances already past that point |
| Java delegate with embedded logic | Logic needs calls to external systems or code that a decision table cannot express | Changes require a code build and deployment, and the engine loads the new class only where the deployment reaches | Unit tests for the delegate, the variables it reads and writes, and retry behavior when an external call fails |
| Decision table called from a business rule task, versioned separately | Rules change often, owners review tables outside the release cycle, and processes should stay stable | A new decision version is deployed by key, and the team confirms which version the business rule task resolves at execution time | Hit policy results per rule, input mapping for missing variables, and regression tests against the decision version before it is released |
Setting up a business rule task in a Flowable process
This sequence takes a decision table from a file in your repository to a business rule task that routes a live process instance, with a check at each stage so the team knows the wiring works before rules and routing grow around it.
Confirm the DMN engine is enabled
A developer confirms that the stack loads the Flowable DMN engine, either through the DMN starter in a Spring Boot application or through the embedded engine configuration in a plain Java or servlet deployment. The Flowable Spring Boot documentation describes starters for the individual process, CMMN and DMN engines, so the team checks the dependency list and confirms the engine bean starts without errors on the target runtime. Done means the application boots, and the DMN service is available to the process engine in the same application context. Confirm the exact starter names and supported runtime versions for your chosen Flowable release before you pin dependencies.
Deploy the decision table
The developer adds the DMN file to the deployment resources and deploys it with the rest of the application, or through the deployment API in environments where definitions are pushed separately. The decision key in the file must match the key the business rule task will call. Done means the decision definition appears in the engine's repository with the expected key and version, and a direct decision execution with sample inputs returns the output the business owner expects. Keep the first deployment small so any mismatch is easy to trace.
Define input and output variable names
The process designer and the decision table owner agree on the process variable names that feed each input column and the names that will receive each output column. Names should be written down in the process model documentation and the decision table's column labels, and they should match exactly, since a typo fails silently in some configurations. Done means both owners have signed off a short mapping sheet listing each input variable, its type and each output variable it returns. Check that required variables exist before the task runs, because a missing input is a common source of unexpected rule results.
Add the business rule task with the decision key
The process modeler places a business rule task in the BPMN diagram and sets its decision reference to the key from the deployed table. The input and output mappings are configured on the task so that process variables flow into the decision and results are stored in named variables. Done means the model validates in the modeler, the task references the correct key, and a deployment of the process succeeds without unresolved references. Confirm the attribute names for your Flowable version in the BPMN modeling documentation, since mapping syntax is the part most often copied incorrectly.
Route results through an exclusive gateway
After the business rule task, an exclusive gateway reads the output variable and sends the instance down the matching sequence flow. Each outgoing flow has a condition that covers every value the decision can return, and one default flow handles anything unexpected. Done means a review of the gateway shows full coverage of the output values listed in the decision table, and the default path is wired to a visible outcome such as a manual review task rather than an silent end event.
Verify with a test process instance
The developer starts a test instance with input values chosen to hit each branch, then checks the history for the decision execution, the stored output variables and the path the instance took. The test should include at least one input that matches no rule so the default flow is exercised. Done means every branch has been reached at least once, the variables in history match the decision table's expected results, and the team has recorded the test inputs in the repository so the check can be repeated after any rule change.
Mapping process variables to decision inputs and using results in gateways
The mapping between a business rule task and its decision table is a naming contract, and most failures in this area come from names that look right but do not match exactly. Each input column in the decision table reads a variable from the process, so the input expression in the table and the process variable it reads must agree in spelling and case. Each output column writes a value back into the process under a name that downstream gateways and expressions then depend on. Before the build starts, ask the team that owns the decision table to list every input and output name, its type and whether it may be absent, and have the process modelers use that same list. Confirm the exact mapping syntax for the business rule task, including how decision inputs and outputs are declared, in the Flowable BPMN and DMN documentation for the version you run, because the attribute and expression forms have changed between major releases.
Type and null handling deserve the same explicit agreement. A decision table compares values according to the types declared in its input and output columns, so a process variable that arrives as text where the table expects a number, or a date held as a string, can match no rule or match the wrong one without raising an error. Missing inputs are more dangerous still. If a process variable is not set when the task runs, the rule may evaluate against an empty value, and a rule written as a simple comparison may silently skip it. Agree with rule owners what a missing value means for each column, whether the process should set a default before the task, and whether a missing input should stop the process with an error. Write a test that starts the process without one input and checks what the gateway receives.
The hit policy decides what the gateway receives. A single-result policy such as FIRST or UNIQUE returns one output value, so the gateway can compare that variable directly against a condition. A multi-result policy such as COLLECT or RULE ORDER returns a list, and an expression that compares that list as if it were a single value will evaluate incorrectly. Choose the hit policy with the gateway in mind, and where the outcome must be a list, have the process handle it explicitly, for example by checking its size or iterating over it. Document the chosen output name and its shape in the process model so that a later change to the hit policy is visible to the modelers who would otherwise break the gateway conditions.
Security and operational risks when processes depend on rules
A process that calls a decision table inherits every weakness of that decision: who can change it, what gets recorded, and what happens when it returns nothing. The cards below cover the controls to settle before a business rule task reaches production. Most of them sit partly in Flowable and partly in your own application, so each card names the check you own.
Who can change deployed decisions
A deployed DMN file changes how every running and future process instance routes work, so deployment rights are a control in their own right. Decide who may deploy decision definitions, whether changes pass a review step with the business owner, and whether the deployment pipeline is the only path to production. Check which deployment endpoints your engine exposes and who can reach them, since a new decision version can take effect without any change to the process model.
Auditability of which rules fired
When a payment, claim or approval is routed by a rule, you need to show which rule matched and which inputs it saw. Confirm that decision execution history is enabled for the decisions that matter, and check how long it is retained and where it is stored. Decide in advance whether the history is retained with the process instance or separately, because high-volume decisions can make history storage a real cost.
Error handling for failed or empty results
A business rule task can fail in two ways: the decision throws an error, or no rule matches and the result is empty or unexpected. Neither should silently pass a default value into a gateway. Define the expected behavior for each case, such as routing to a manual review path or raising an incident, and test that the process reaches it. Confirm how your hit policy and default output handle the no-match case before go-live.
Access control on the engine REST API
If applications or staff reach decisions over the REST API, the engine does not decide who may execute, read or deploy them. Those authorization checks belong to your application or gateway. Map each caller to the decision keys it needs, restrict deployment operations to a release identity, and log which client executed which decision. Test that a caller without rights cannot reach a decision by calling the endpoint directly.
Monitoring through the actuator endpoint
The Flowable Spring Boot starters expose an actuator endpoint at /actuator/flowable for monitoring running processes. Treat that endpoint as operational data that may reveal process and deployment detail, so restrict who can read it and keep it off public networks. Decide which alerts matter for rule-driven work, such as failed jobs or a rise in no-match outcomes, and confirm that your monitoring stack collects them.
Identity and secrets used by the caller
The application that starts processes or calls decisions needs an identity and credentials, and those become a privileged path into the engine. Use a dedicated service identity with only the permissions it needs, store its secrets in your secrets manager rather than in configuration files, and rotate them on a schedule you can prove. Where the engine delegates identity to your own services, confirm which identity service implementation is in use and how it is reviewed.
Questions teams ask before building business rule tasks
What drives the effort of a Flowable business rule task integration?
Effort depends mainly on how many decisions the process calls, how many process variables must be mapped into each decision's inputs, and how the results feed gateways and later steps. Each decision needs its input and output contract agreed, a mapping from process variables to those columns, and a test that shows the gateway routes correctly. Data types, null handling and the number of distinct outcomes add work because each one is a path the process must handle. Ask any partner to break the quote down by decision count, mapping complexity and the number of process paths that consume results.
Can an internal team build Flowable rule tasks without a partner?
A team with Java and BPMN experience can build a simple rule task using the Flowable documentation, the Spring Boot starters and the DMN engine's Java API. Teams usually find the harder parts are decision design, deciding which system owns the rule, and testing rule changes against business expectations. Flowable's open source distribution is licensed under Apache 2.0 and the community forum is available, but professional services and partners are offered separately. Decide early whether your team has time to own decision tests, deployment pipelines and upgrade work after the first release.
What do business owners need to provide for a rule task?
Business owners must supply the decision logic in a form that can be checked: the inputs, the allowed values, the outcomes and the rule order or overlap rules that define a correct answer. They also need to review sample cases and sign off on expected results before release. Without named owners who can answer edge-case questions, the build stalls or the rules drift from the policy they were meant to encode. Ask your partner to list the review sessions, the sample data you must provide and who approves changes.
How long does a rule task integration take?
No duration can be stated here without a written scope, so the answer depends on the factors already named: the number of decisions, the number of process paths that depend on them, the integration pattern and the review cycles with business owners. A single decision wired to one gateway is a smaller job than a set of decisions shared across several processes and called over REST by other applications. Ask for a timeline that lists milestones for design, build, testing and release, and that states which inputs from your side each milestone depends on.
Does a rule task need to change when Flowable is upgraded?
Upgrading Flowable changes the platform baseline, and the DMN engine is part of that baseline, so rule task code should be retested after every version move. Flowable's release notes for version 8.0.0 describe an upgrade to Spring Framework 7 and Spring Boot 4 with no backward compatibility for Spring Boot 3, and Jackson 3 as the default JSON library. Teams that reference the JSON layer or test with JUnit 3 or 4 must plan changes. Keep decision tables and rule task tests in version control so a regression run can confirm behavior on the new version.
Should decisions live in the process or in a separate version cycle?
Keep decision tables as separately deployed DMN files so business rule changes do not require redeploying the process. The rule task references a decision key, and the running process picks up the deployed decision version according to the rules documented for your Flowable version. Confirm in your environment how version selection behaves for instances already running, because that determines whether a rule change affects in-flight cases. Ask your team to test both a new instance and an in-flight instance before you adopt this pattern.
What should we check before accepting a rule task design?
Check that every process variable mapped to a decision input has a defined type, that every decision outcome leads to a gateway path, and that a default path exists for results the table does not cover. Confirm that the hit policy matches the output you need and that decision history retention meets your audit requirements. Ask whether the design includes tests for each rule and for the gateway behavior, and whether the decision owner can review the test results without engineering help.
Where to read the Flowable documentation for this feature
Start with the Flowable open source page and the flowable/flowable-engine GitHub repository, then read the getting started guide and the Spring Boot docs before you write a decision call in a business rule task. The open source page confirms what the engines cover and the Apache 2.0 license, and the repository shows the release history. The getting started guide explains how the DMN engine is embedded in your application, whether that is a plain Java SE process, a servlet container or a Spring application. The Spring Boot docs cover the DMN starter and the actuator endpoint at /actuator/flowable, which matters if your decision engine runs inside a Boot service. Flowable open source is the natural first read.
Check the details below in the docs for the exact Flowable version you run, not the latest one. Confirm how the business rule task refers to a decision by key and how the decision result is written back to process variables, since these conventions have changed across major versions. Confirm the Spring Boot and Java baseline, because the 8.0.0 release moved to Spring Boot 4 and Spring Framework 7, and the 7.x line used Spring Boot 3. Confirm how the DMN engine is configured in your database and async executor settings, and whether DMN history is written by default. Record the version you verified in your design notes so that the next upgrade starts from a known baseline. The flowable-engine releases page lists what changed in 8.0.0.
How DeployOpen scopes and delivers Flowable DMN integrations
DeployOpen plans, implements, tests, documents and supports self-hosted Flowable engines inside your own infrastructure. For business rule tasks, that means agreeing in writing which decisions the process calls, how variables map to inputs and outputs, and who owns each rule version before any build starts.
How we scope
- Engagements are fixed-scope, with the list of process models and decision tables agreed in writing before work starts.
- The written scope names each business rule task, its input and output variables, and the gateway logic that consumes each result.
- We confirm which rule changes must ship without a process redeployment, and record the owner who approves each decision table.
- Scope also states the Flowable version, database type and deployment target your environment runs.
How we build
- We map process variables to decision inputs and outputs, and document any type conversions or default values in the design.
- Each decision is called through a business rule task with a defined key, and its results route through explicit gateway conditions.
- Decision versions are managed separately from process definitions, so rule releases follow their own review and deployment steps.
- Test cases cover each rule and hit policy path, and run against the deployed DMN files in a non-production environment.
How we hand over
- Handover includes the process and decision inventory, variable mapping tables and the release steps for new decision versions.
- Documentation explains which version a running process instance picks up, so operators can predict the effect of a rule change.
- Your team receives the test suite, with instructions to extend it when business owners request new rules.
- Handover records the configuration and deployment steps needed to reproduce the environment in your infrastructure.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, scoped separately from the original build.
- Support can cover Flowable version upgrades, including review of any changes to Java, Spring or Jakarta baselines.
- We can review rule changes against the regression suite and the business owner sign-off before they reach production.
- Your team should confirm support terms, response expectations and ownership of rule changes in the written agreement.
