Flowable decision table versioning

Deploying Flowable decision tables without redeploying processes

Flowable DMN decisions are deployed as separate definitions that processes call by key, so a rule change does not have to ride along with a process model release. A business rule task names the decision it evaluates, and the engine resolves that key against the decision definitions deployed to it. Teams that treat the decision table as a versioned asset in its own right can change eligibility limits, pricing bands or routing rules on the business's timetable, while the process model stays stable.

This matters most in three situations. The first is frequent rule change: when credit thresholds, fee schedules or approval limits move monthly and the process flow around them does not. The second is multiple business owners, where a risk team, a product team and an operations team each own different tables and need to release them independently. The third is tenant-specific rules, where one platform serves several business units or customers with different thresholds. This page covers how decision definition keys and versions work, why one decision per file keeps releases reviewable, how tenant-specific decisions are deployed, and which version a running process instance picks up after a new deployment.

Flowable's engines are Apache 2.0 Java engines for BPMN, CMMN and DMN, with Java and REST APIs, according to the Flowable open source page. The exact rules for version resolution, including how the engine chooses between deployed versions and how instances already in flight are treated, must be confirmed against the Flowable DMN documentation for the version you run. Confirm this in a test environment before you rely on it in a release process.

Versioning options for decision tables and when each fits

This table compares three Flowable decision patterns and one version-pinning option for callers that must stay on a fixed rule version. Read each row by the change it suits, what a reviewer must check, and how calling processes and day-to-day upkeep are affected. Items marked confirm need checking against the Flowable DMN documentation for your engine version before you rely on them. The key strategy decides who is affected by a rule change, so settle it before the first production deployment.

Pattern	Suits this change	Reviewer must check	Effect on callers and upkeep
New deployment under the same key	A correction or policy update that applies to every caller and keeps the same inputs and outputs.	Input and output names and types are unchanged, and the hit policy still fits every caller. Confirm which version a running process uses.	Callers pick up the latest version when they next evaluate the decision. Low upkeep, but one faulty version affects all callers at once.
Distinct key per rule family or variant	A new product line, segment or channel whose rules differ in inputs or outputs from existing callers.	Each key has a named owner, and callers are moved to the new key deliberately in their process models.	Callers change only when their model is edited and redeployed. Each key adds catalog entries, tests and review steps to maintain.
Tenant-specific decision deployments	Rules that differ by customer, legal entity or region on one platform serving several tenants.	Tenant identifiers match the calling process's tenant, and no tenant falls back to a shared rule by accident. Confirm the fallback behavior in the docs.	Deployment count grows with the number of tenants, so deployment automation and drift checks become necessary.
Shared key with a version pinned by the caller	Callers that must run a fixed rule version while a newer version is tested or approved.	Confirm whether a caller can reference a specific version and how that reference is updated during a release.	Each caller needs a release step to move forward. Track which callers use which version so stale pins are found.

How to release a decision table change safely

This sequence moves a DMN rule change from agreed key and version policy to a verified deployment, so each release is tested against the file that will run and you can show which version every new and running instance uses. Each step ends with a check that either passes or sends the change back.

Agree the decision key and version policy
The rule owner, the process or case owner and the platform team agree the decision key for each decision, the naming convention for DMN files, and how a change is labeled as a new version. They also decide which processes and cases call each decision by key, so a rename cannot break a caller unnoticed. The step is done when the agreement is written down and each decision has exactly one owner who can approve a change.
Author one decision per DMN file
The rule author edits the decision table in its own DMN file, with one decision definition per file, so a deployment carries only the change under review. Inputs, outputs, hit policy and the decision key are checked against the agreed naming convention before the file is committed to version control. The step is done when the diff shows only the intended rule rows and the file passes the team's review checklist.
Test the change against the deployed file
The engineer runs the test suite against the DMN file as it will be deployed, not against a copy typed into the test, and the business owner reviews the expected results for changed and unchanged cases. Regression cases cover rules the change should not affect. The step is done when every test passes and the owner has signed off the expected outputs in writing.
Deploy through the chosen path
The platform team deploys the file using the path the organization has standardized on, whether the Java API, the Spring Boot starter or the REST deployment endpoint, and the Flowable getting started and Spring Boot documentation cover the mechanics. The deployment is recorded in the pipeline with the file's commit and the environment it reached. The step is done when the deployment completes without errors in the target environment.
Verify the deployed decision version
The engineer queries the deployed decision definitions by key and confirms that the new version number, the expected tenant, and the file's content match the release record. A test execution of the decision in the target environment should return the expected result for a known input. The step is done when the deployed version and the test result both match what was approved.
Confirm which version each instance uses
The engineer checks which decision version new executions resolve to, and which running process or case instances already hold a reference to an earlier version, using the engine's query capabilities and the behavior documented for your Flowable version. Teams should confirm this with their own test instances before relying on it for production, because the pickup rule determines whether in-flight work follows the change. The step is done when the expected version split is recorded and the operations team knows which cases will see the new rules.

Tenant-specific decisions compared with shared decisions

A single decision definition serves every customer or business unit. The rule owner is usually a central function such as risk, pricing or operations, and every change applies to all consumers at once. Deployment is simple because there is one decision key and one set of versions to track, and the release pipeline only needs to confirm that the new version is the one processes and cases resolve.

Ownership: One team approves every row, so reviews must cover all consumers, not just the one that asked for the change.
Deployment scope: One DMN file is deployed to the engine and referenced by key from every process or case that calls it.
Pipeline checks: Run regression tests against the full rule set and confirm that version increments are visible to running and new instances.
Blast radius: A wrong rule affects every consumer, so staged rollout by process version matters more here.
Confirm: Check how your Flowable version selects the latest deployed version for a decision key and whether a running process pins an earlier version.

Before adopting this model, confirm with your business owners that no consumer needs an exception that would later force a second decision.

Why one decision per file simplifies reviews and rollback

Keeping one decision per DMN file gives each decision its own review, its own version history in source control and its own deployment unit. When a rule change touches only the eligibility decision, the diff shows only the eligibility decision, the reviewer sees one set of inputs and outputs, and the business owner signs off on one artifact. Rollback becomes a matter of redeploying the prior file for that decision key, without pulling in unrelated rules that happened to share a file. For a team managing dozens of decisions, this is the difference between reverting one change and untangling a combined file that several owners edited in the same week.

The trade-off is volume. Many small files mean more files to track, and decisions that share inputs, such as a customer risk band or a product catalog, can drift apart if each file defines them separately. Mitigate this by agreeing on a naming convention where the decision key states the business question and the file name matches the key exactly, for example loan-eligibility.dmn carrying a decision with the key loanEligibility. Keep a short register that maps each key to its owning team, its calling processes and cases, and its input variables. Confirm in the Flowable documentation how your chosen version of the engine identifies and stores definition versions before you rely on file names alone for traceability.

Rollback is only as reliable as the record behind it. Tag each release in source control with the decision keys and file hashes deployed, and keep the prior file in the repository so that a revert produces an exact previous definition. Before a rollback, confirm which running process instances and cases are bound to the newer version, since a rollback changes what new executions pick up, not what already-running work has evaluated. Test the reverted file against the same regression cases used for the release, so that the rollback itself is verified rather than assumed.

Release risks that break rule changes in production

Rule changes in Flowable usually fail at the seams: the decision key, the version a process resolves, the tenant that received the file, and the inputs the rule expects. Each risk below names the early signal to watch for and the control that keeps it from reaching production.

A deployed key shadows an older definition

When a new DMN file reuses a decision key that already exists, the engine deploys it as a higher version and newer process instances pick it up. Teams often assume the old rules are still in force for in-flight work, which is not always true. Early signal: decision results change for inputs that were unaffected by the edit. Control: review the key and version of every decision file in the release diff, and confirm with the vendor docs which version a running process resolves before you ship.

Processes call a key that no longer exists

A business rule task references a decision key by name. If a release renames or removes that key, the process fails at the point the task runs, often hours or days after deployment. Early signal: failed jobs or exceptions naming a decision key that the engine cannot find. Control: keep a register of which processes and cases call which decisions, and block any release that removes a key still referenced in that register.

Tenant deployments drift apart

Teams that serve several tenants with tenant-specific decisions can end up with rule sets that differ in ways nobody intended. A fix shipped to one tenant may never reach another. Early signal: the same decision key returns different results for the same inputs across tenants. Control: store every tenant variant in version control with a documented list of intended differences, and compare deployed decision output across tenants as part of each release.

Inputs no longer match input columns

A decision table reads named input expressions. If a process still passes the old variable names or types after a column changes, the rule may match nothing and return empty results without an obvious error. Early signal: a rise in default or empty outputs after a change that touched only the table. Control: check each calling process's variable mapping against the new input columns, and add a test case with a complete input set for every changed column.

Version history lives outside source control

If decision files are edited directly in a running environment or in a modeler without commits, the engine keeps versions but nobody can explain what changed or why. Auditors and incident responders then depend on deployment logs that may be incomplete. Early signal: a deployed version with no matching commit or change ticket. Control: deploy only from a tagged repository state, and record the deployment ID, version and approver together so each running decision traces back to one reviewed file.

Rule changes skip testing

Business owners often ask for a quick rule change that bypasses the test suite and goes straight to production. Without regression tests, an edit to one rule can change the hit set of another, especially with overlapping rules. Early signal: a release with no test diff for a changed decision file. Control: make the decision test suite a required gate in the pipeline, and require a named business owner to sign off on expected outputs for each changed rule.

Who can deploy decisions and how deployments are audited

Treat deployment as a privileged production change from the start. The Flowable REST deployment endpoints and the Java repository API can add a new version of a decision table, and the engine will use it for new evaluations as soon as it is deployed. That makes deployment rights, the credentials your pipeline uses and the review gate before a .dmn file reaches production part of the security design, not an afterthought for the platform team. Decide which people and which service accounts may deploy decisions, separate those rights from the rights to start processes or read decision results, and require that every production deployment passes through the same review and approval steps as code. Confirm with the Flowable security documentation and your own hosting application how deployment endpoints are authenticated and whether they can be restricted by role, because the engine leaves much of the authorization of these actions to the application that hosts it.

Once a rule change is live, the Flowable actuator endpoint at /actuator/flowable gives operations teams a signal about running work, which helps detect a bad release by watching instance and job behavior after a change. It does not, however, tell you who deployed which file or when, so that record has to live in your own change system. Keep an entry for each deployment that links the .dmn file version in your source repository, the decision key and version the engine reported, the pipeline run, the approver and the environment. Compare that record with the decision history the engine stores when rules are evaluated, so an auditor can trace a decision back to the approved change that produced it. Ask your team to confirm which deployment details the engine persists by default in your database configuration and what your audit logs retain, and agree on retention periods with compliance before go-live.

Limits to confirm in your Flowable version and environment

Versioning behavior for decision tables depends on the exact Flowable release, the database and framework baseline beneath it, and how your application handles tenants. The cards below list the points to confirm in the release notes, configuration docs and with the vendor before you commit to a release process.

Version resolution rules

Confirm how the DMN engine chooses a decision when several deployed versions share one decision key, and whether it selects the latest version by default or accepts an explicit version reference. Check this against the release you run, because the rule should be written down in your own release process rather than assumed from earlier versions. Test with two deployed versions of one key before you rely on the behavior.

In-flight instances and new decisions

Confirm whether a process or case instance that is already running picks up a newly deployed decision version when it reaches a decision task, or keeps the version it started with. The answer determines whether a rule change can take effect immediately or only for new instances. Ask the vendor for the exact behavior of your release, and test it with a long-running instance paused on a wait state.

Supported database types and versions

The configuration docs list the database types Flowable supports, including H2, MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server, and note a MySQL precision constraint for older versions. Confirm the exact database versions your release supports, because deployment history and decision metadata are stored there. Check the version matrix before you choose a database for a rule-heavy environment.

Spring Boot and Java baseline

If you embed the engine with Spring Boot starters, confirm which Spring Boot line your chosen Flowable release supports, and which Java version it requires. Flowable 7 moved to Java 17, Spring Boot 3 and Jakarta EE, and Flowable 8 moved to Spring Framework 7 and Spring Boot 4. Confirm the baseline for your release before you pin your parent POM or build image.

Flowable 8.0.0 upgrade effects on decisions

The Flowable 8.0.0 release notes describe removing support for Spring Boot 3 and for JUnit 3 and 4, and changing the default JSON library. Check whether any of these changes affect your deployed DMN files, REST calls that carry decision inputs, or test suites that verify rule versions. Plan a regression run of your existing decision definitions against the new release before you move production rules.

Tenant handling limits

Confirm whether tenant-specific decisions are supported by your release as a built-in deployment feature, and how decisions with the same key are isolated between tenants. Ask how the engine resolves a decision when a tenant has no version of its own, and whether tenant identifiers are passed through the REST API. Test isolation with two tenants that use the same decision key before you give tenants independent rule release cycles.

Questions teams ask before deploying Flowable decision tables

How much effort does a decision versioning setup take?

The effort depends on how many decision tables you release, how often their rules change, and how much of the release process you want automated. A small set of decisions maintained by one team is a different job from dozens of decisions shared across several business lines. The main drivers are the number of decisions, whether each decision has its own file and key, how many tenants need their own variants, how mature your deployment pipeline already is, and how deeply each rule change is tested before release. Ask any partner to split its estimate into design, pipeline work, test work and handover so you can see where the effort sits.

What drives the cost of a Flowable decision tables engagement?

Cost follows the written scope, not a list price. The largest components are usually the number of decision tables, the number of processes and cases that call them, the tenant model, the integration of the deployment pipeline, and the testing depth agreed for each hit policy. Some work is one-time, such as designing key and version conventions and building the first pipeline. Other work recurs, such as reviewing rule changes, maintaining regression suites and upgrading the engine. When you request a quote, ask which items are fixed, which are optional, and what a later change to scope would cost.

What does the work need from our team?

Decision tables encode business policy, so your team has to supply the rules and the people who own them. Expect to name a business owner for each decision, provide current rule sources and historical outcomes, and agree who approves a change before it is released. Your platform or engineering team will need to give access to the repository, the deployment pipeline and the target environments. Your security team should confirm who may deploy decisions to production. Without these owners in place, the technical work tends to stall on questions about intended behavior.

Can our own team run decision versioning without outside help?

Yes, if your team already runs Java services and a deployment pipeline and has the time to learn how Flowable keys, versions and deployments behave. The engine's documentation covers the core concepts, and the Flowable open source project is licensed under Apache 2.0. Outside help is most useful for the design decisions that are hard to reverse, such as the key naming scheme and the tenant model, and for building regression tests that business owners trust. Many teams split the work: an outside partner sets up the foundation and the internal team takes over the routine release process.

How long does a first decision release take?

No duration is fixed in advance. A first release includes agreeing the key and version conventions, placing each decision in its own file, wiring the deployment step, and testing at least one rule change end to end. The time it takes depends on how many decisions are in the first release, how many business owners must review rules, and whether a deployment pipeline already exists. Ask for a timeline tied to a written scope, with the review steps for business owners listed as separate milestones so delays in sign-off are visible.

How does a Flowable upgrade affect existing decision tables?

Decision tables are deployed to the engine, so an engine upgrade can change how the engine loads, evaluates or stores them. Major releases can also change the Java, Spring and Jakarta baseline, which affects the application that hosts the engine. Before upgrading, check the release notes for the version you plan to use, rerun your decision regression suite against the new engine, and confirm that deployed decisions and running instances behave as expected. The Flowable 8.0.0 release notes describe a move to Spring Framework 7 and Spring Boot 4 without backward compatibility for Spring Boot 3, so host applications may need changes before the engine can be upgraded.

Which tenant model should we choose for tenant-specific decisions?

The right model depends on how much rule logic differs between tenants and how many tenants you run. Some organizations keep one shared decision with tenant-specific inputs, while others deploy a separate decision per tenant under a naming convention. Each option changes how many files you maintain, how tests are organized and how an audit of a given rule is answered. Ask for a written comparison of these options for your own decisions before choosing, and confirm how your chosen model will be tested for each tenant.

How DeployOpen scopes and delivers Flowable decision releases

DeployOpen plans, builds and hands over Flowable decision table releases inside your own infrastructure, so rule changes ship on a controlled version path without redeploying the processes that call them. Engagements are fixed-scope, with the decision keys, versioning rules and tenant model agreed in writing before the build starts.

How we scope

The written scope lists which decision tables move under versioned releases and which processes and cases call them.
We confirm the decision key naming, one-decision-per-file layout and version rules your business owners will follow.
Tenant-specific decisions, if needed, are named and bounded in the scope before any build work begins.

How we build

We set up the deployment pipeline that publishes decision definitions to your Flowable engine in a repeatable order.
We verify, for each caller, which decision version a running process instance picks up after a release.
We test decision releases against deployed DMN files, covering each hit policy in use before promotion.

How we hand over

You receive documentation of the key and version conventions, the release steps and the rollback procedure.
Your team gets a walkthrough of how to add a decision version, retire one and confirm which version is live.
Test cases and the release checklist are delivered in your repository, so your owners can extend them.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after the handover.
Retainers can cover Flowable version upgrades and regression runs when decision tables change.
Confirm response expectations and upgrade coverage in the written retainer scope before signing.

Deploying and versioning Flowable decision tables