Choosing a Flowable DMN hit policy before the first rule is written
The hit policy determines how a Flowable DMN decision table turns matching rules into a result, and it should be chosen before the first rule is written. A single-answer policy such as FIRST, UNIQUE, ANY or PRIORITY returns one outcome, while OUTPUT ORDER, RULE ORDER and COLLECT return a list. If the team picks the wrong family, the table may still run, but the process or case downstream receives a shape it does not expect, or a second rule quietly changes the answer. The decision therefore belongs in the design phase, alongside the input and output columns, not in a later tuning pass.
The hit policy controls three things: how many rules may match an input row, whether overlapping matches are an error or are resolved by order or priority, and what the engine returns when several rules match. Teams need to settle it whenever a decision is consumed by a BPMN business rule task, a CMMN decision task or the REST decision service, because each caller reads the output differently. The policy also decides how much rule overlap the table tolerates. Tables built on UNIQUE fail at execution when two rules match, which is useful for catching gaps in coverage, whereas PRIORITY and RULE ORDER accept overlaps by design. Confirm the exact behavior of each policy, including strict mode, against the Flowable DMN documentation for the version you run before you commit.
Before writing rules, record three answers for each decision: whether the caller needs one value or a list, whether the business owner expects rules to overlap, and how a no-match case should be handled. Write a small set of illustrative test inputs that include overlaps and gaps, then run them against a prototype table under each candidate policy. Flowable is released under Apache 2.0 and its engines can be embedded in your own Spring or Java application, so this prototyping can happen in your own development environment. Keep the chosen policy in the design record so that later rule changes, reviewed in the Flowable open source page, do not silently change the result shape.
Single-result policies: FIRST, UNIQUE, ANY and PRIORITY
FIRST returns the output of the first matching rule in table order and ignores any later matches. Overlapping rules are accepted by design, so the row order carries the decision logic. It suits ordered exception lists, such as a specific rule placed above a default row at the bottom of the table. (Illustrative: a premium discount row for a named customer segment sits above a general row for all customers.)
- Result: one output, taken from the top-most matching rule.
- Overlaps: tolerated without error, and later matches never change the result, so a broad rule placed above a narrow one hides the narrow rule.
- Maintenance risk: reordering rows changes outcomes, so reviewers must read the row order as part of the logic.
- Typical use: ordered exceptions with a default row at the bottom.
- Auditability: the matched rule is the only one that determines the output, which makes the path easy to explain when the rule set is short.
Check that every overlap is intentional, and confirm with the Flowable docs how strict mode treats overlapping matches for FIRST before you rely on it.
UNIQUE expects each set of inputs to match at most one rule, and it returns that rule's output. The policy treats an overlap as a defect in the table, not as something to resolve by order or ranking. It fits complete, non-overlapping tables where every case has exactly one correct answer, such as mapping a product code to a single category.
- Result: one output when exactly one rule matches.
- Overlaps: not tolerated, because two matching rules mean the table definition is wrong.
- Gaps: an input that matches no rule produces no output, so you must decide how the calling process or case handles that case.
- Typical use: classification tables with one answer per combination of inputs.
- Review cost: the policy shifts effort to table design, since authors must prove the rules are mutually exclusive and cover the input space.
Before release, test both an input that matches two rules and an input that matches none. Confirm with the Flowable docs what strict mode reports in each case, because the failure behavior is what your operations team will see in production.
ANY allows several rules to match the same inputs, provided every matching rule produces the same output. The engine returns that shared output. Overlap is tolerated only when the answers agree, so the policy works well when several independent triggers all lead to the same outcome, such as several risk indicators that each require the same manual review.
- Result: one output, identical across all matching rules.
- Overlaps: tolerated only when outputs agree. A matching pair with different outputs is an error.
- Change risk: adding a rule with a different output later can break paths that previously passed, so the change must be tested against all existing overlaps.
- Typical use: several independent triggers that all lead to the same referral or approval step.
- Clarity: the table documents that different conditions reach the same answer, which helps reviewers who ask why a case was routed.
Test each overlapping pair of rules for matching outputs, and include a regression case for every new trigger. Confirm with the Flowable docs how strict mode reports a disagreement between matched rules.
PRIORITY allows several rules to match and returns the match whose output ranks highest. The ranking comes from the order of values defined for the output, not from the row order of the table. It fits cases where more than one outcome can apply and one must win based on business severity, such as a fraud hold that overrides a routine review flag. (Illustrative: a hold outcome ranks above a review outcome, so a case matching both returns the hold.)
- Result: one output, the highest-ranked among the matching rules.
- Overlaps: tolerated by design, and the ranking resolves them without an error.
- Ranking definition: priorities depend on the output value list, so changing that list changes outcomes across the whole table.
- Typical use: severity escalation where a stronger outcome must override a weaker one.
- Explainability: reviewers must understand the ranking to predict results, so document it next to the table.
Review the output value list with the business owner before release, and add test cases for combinations where two outcomes match. Confirm with the Flowable docs how the ranking is defined and how strict mode treats overlapping matches under this policy.
List policies for multi-result decisions: OUTPUT ORDER, RULE ORDER and COLLECT
List hit policies return every matching rule instead of one result, so the process or case must handle several values at once. The three list policies differ in how the returned values are ordered and whether they can be combined into a single aggregate. Pick the policy from the shape of the downstream work, then confirm the behavior against the Flowable version you run.
OUTPUT ORDER
OUTPUT ORDER returns all matching results sorted by the order of the output values you define in the table. Use it when downstream logic needs a predictable sequence, such as a ranked list of required approvals or checks that must run in a fixed priority. Because the sort depends on output definitions, reviewers must confirm that the output order column matches the sequence the business expects. Downstream code should iterate the returned list in order rather than assume any particular rule was first.
RULE ORDER
RULE ORDER returns all matching results in the sequence the rules appear in the decision table. It suits tables where the author controls the sequence through row placement, such as a stepwise list of notifications or escalation steps. Any change that reorders rows changes the output order, so teams should treat row order as part of the rule contract and cover it in regression tests. Gateways or tasks that consume the list should not depend on the count being fixed, because edits can add or remove matches.
COLLECT
COLLECT returns matching outputs as an unordered collection, and can apply an aggregate such as sum, count, minimum or maximum when the table is set up for it. Use it when the process needs a total, a count or a set of values rather than a sequence, for example summing fees across applicable products. Confirm which aggregation functions your Flowable version supports and how it handles empty matches before you build on them. Downstream steps must still handle zero matches and non-numeric outputs.
Handling empty and multiple results
A list policy can return no matches, one match or many, and the process must handle all three. Add a gateway branch for the empty case, and avoid assuming a list has a single element just because the sample data had one. Test each list policy with zero, one and several matching rules so the empty path is exercised before release. Document the expected behavior next to the table so reviewers and developers read the same contract.
Choosing between order and aggregation
Choose OUTPUT ORDER or RULE ORDER when each returned value is an action or item that must be processed individually. Choose COLLECT when the result feeds a single calculation or a membership check. Mixing these needs in one table often leads to brittle downstream logic, so split the decision into two tables if both a sequence and a total are required. Ask the Flowable team or your own tests to confirm the exact result shape each policy returns in your deployment.
Which hit policy fits which decision
This table compares the seven hit policies in Flowable DMN decision tables by result shape, overlap tolerance and strict mode behavior, with an illustrative business case for each. Read the overlap column first, because it determines whether a table can grow without breaking existing results. Confirm each cell against the Flowable DMN documentation for your target version before relying on it in production.
| Hit policy | Result shape | Overlap tolerance and strict mode | Illustrative example |
|---|---|---|---|
| FIRST | One output from the first matching rule in table order | Overlaps allowed; table order decides the result. Confirm strict mode handling. | Discount band where the first matching band applies |
| UNIQUE | One output; exactly one rule may match the inputs | No overlaps tolerated. Overlapping matches are a violation, and strict mode is expected to raise an error. Confirm. | Country code mapped to exactly one tax zone |
| ANY | One output; all matching rules must return the same output | Overlaps allowed only when matching outputs agree. Confirm how conflicts are reported. | Several rules that each flag the same approval step |
| PRIORITY | One output chosen from a priority list of output values | Overlaps allowed; the highest-priority output wins. Confirm the priority order setup. | Risk outcome where decline outranks manual review |
| OUTPUT ORDER | List of outputs sorted by output value priority | Overlaps allowed; all matching outputs are returned in sorted order. Confirm sort setup. | Ranked list of checks a case must complete |
| RULE ORDER | List of outputs in the order the rules appear in the table | Overlaps allowed; all matches are returned in rule order. Confirm list ordering. | Ordered list of notification templates to send |
| COLLECT | List of outputs, or a sum, count, minimum or maximum when an aggregator is set | Overlaps allowed; all matching rules contribute. Confirm the aggregator options for your version. | Total of all fees that apply to one order |
How strict mode changes what a rule set may do
Strict mode determines how much tolerance a Flowable decision table has for rule overlaps and gaps, so it belongs in the hit policy decision, not in a later configuration pass. Before you choose a hit policy for a table that must run under strict validation, confirm in the Flowable configuration and DMN documentation exactly which checks strict mode performs, whether they run at deployment, at evaluation, or both, and what the engine reports when a check fails. Treat the answers as properties of your Flowable version, since behavior can change between releases such as the 8.0.0 line. Do not assume that a table which evaluates in a permissive setting will deploy or evaluate the same way under strict validation.
The practical risk is that overlapping or missing rules can surface at different points. An overlap that is harmless under FIRST may still be a validation failure under UNIQUE, and a gap where no rule matches may produce a null or empty result that a downstream gateway handles badly. Work out, for each decision, where a failure would appear: a deployment error caught by your pipeline, a runtime exception inside a running process, or a silent empty result that only shows up in a customer case. Each of these needs a different owner and a different alert.
Test both sides of the table. Write test cases that should match exactly one rule, cases that match several, and cases that match none, and run them against the deployed DMN file under the same strict settings your production environment uses. Keep the non-matching cases in the regression suite as well, because a rule change that removes coverage is easy to miss when only the happy path is tested. Record the observed behavior for each case so that a later Flowable upgrade can be checked against a known baseline.
How to set a hit policy and verify it in a Flowable decision table
This sequence takes a decision from business question to a tested Flowable DMN table, so the hit policy you choose returns the result shape your process expects before any BPMN or CMMN model calls it.
Define decision inputs and outputs
Start by listing the input columns the decision needs, such as customer segment, amount or region, and the output columns the calling process will read, along with each column's data type. Agree this list with the process owner and the business owner of the rule, because every later choice depends on it. Done means you have a written input and output table with names that match the process variables you plan to pass in, and no output is left without a named consumer.
Choose the hit policy from the decision requirement
Decide whether the decision should return one result, several results or a combined value. Use FIRST or PRIORITY when a single answer is wanted and rules may overlap, UNIQUE or ANY when overlaps should be treated as errors or as agreeing answers, and OUTPUT ORDER, RULE ORDER or COLLECT when the caller needs a list. Confirm the exact behavior of each policy, including strict mode, in the Flowable DMN documentation for the version you run, and record the chosen policy with the reason for it. Done means the policy and its rationale are written next to the decision.
Write rules, including one deliberate overlap
Author the rules in the decision table, keeping one rule per business case and writing a single overlapping case on purpose, so you can see how the chosen policy handles it. Keep input entries narrow enough that the overlap is intentional and document why it exists. Done means every rule has a description and the overlap case is named in the file, so reviewers know which rows are expected to match together.
Deploy the DMN file to a test engine
Deploy the decision file to a test Flowable engine that matches the production version, using the DMN engine's deployment path in your development setup or a local REST call. Use a non-production database and tenant so test definitions never reach live data. Confirm the deployment returns a decision key and version, and that the definition appears in the engine's repository. Done means the decision is listed with the expected key and version number.
Run test inputs for each policy outcome
Write test inputs that cover each expected outcome: no rule matches, one rule matches, the deliberate overlap matches, and any boundary values in your input columns. Execute each input against the deployed decision and record the raw result. Compare the outcome with what the hit policy should produce, including what happens to the overlap row. Done means every test input has a recorded expected result and an actual result, and any mismatch is explained or fixed in the table.
Check the result shape before connecting to a process
Inspect the output structure for each policy: a single value or a list, the output variable names, and the data types the calling process will read. Check how the empty result is returned, because a process gateway may fail on a null value. Confirm the result shape matches the input and output table from the first step. Done means the output contract is written down and the test results match it, so the BPMN business rule task or CMMN decision task can be wired to it without guessing at the structure.
Governance and operational risks of hit policy changes
A hit policy decides how many rules count and what the caller receives, so changing it changes behavior for every process and case that calls the table. The cards below cover the risks to review before a change reaches production, and they point to deployment, testing and history as the sibling topics that control them.
Changed results for running callers
A hit policy change alters the output shape or the selected result for every caller that evaluates the table, including processes that started before the change. A switch from FIRST to COLLECT, for example, can turn a single value into a list that a downstream gateway or variable mapping does not expect. Before release, list each calling process and case, confirm how it reads the output, and decide whether in-flight instances need the old behavior. Deployment versioning covers which version a running instance picks up.
Unreviewed overlaps reaching production
Overlapping rules are tolerated differently by each hit policy. UNIQUE fails at evaluation when two rules match, while FIRST and PRIORITY quietly pick one rule by row order or priority. A new rule added by a business owner can therefore create an overlap that changes outcomes without any error. Require an overlap review for every table change, and record which overlaps are intended. Test cases per rule and hit policy are covered in the testing topic.
Silent changes from rule order
Under FIRST and RULE ORDER, row position determines the result, so reordering rows during an edit can change decisions without adding or removing any rule. Editors may treat row order as cosmetic, which makes this one of the easier changes to approve by accident. Treat row order as part of the decision logic, and include a regression run whenever rows move or sort.
Decision history for audit
When a rule change is questioned later, the team needs evidence of which version ran and which rules matched for a given case. Confirm with your team what DMN execution history records in your Flowable version, how long it is kept, and who can read it. The history topic covers the storage trade-off for high-volume decisions and the option to disable history persistence in Flowable 8.
Ownership of rule changes
A hit policy change affects engineering, the business owner who wrote the rules, and any team that consumes the output. Without a named approver for each table, changes can ship on the strength of a passing test alone. Agree in advance who reviews the hit policy, who signs off on overlaps, and who is notified when output shape changes. Confirm the approval steps with your change management process before the first production release.
Separating rule releases from process releases
A decision table that changes on its own schedule needs its own release path, so a rule fix does not force a process redeploy or a process change does not silently alter a table. Confirm whether your pipeline versions decision definitions independently, and whether calling processes pin a specific decision version or pick up the latest. The deployment and versioning topic describes decision keys, versions and tenant-specific decisions.
Questions teams ask before choosing a hit policy
What drives the cost of choosing and implementing a hit policy?
The main cost driver is the number of rules and how many of them overlap on the same inputs. A table with a few rules that never overlap is quick to settle on a hit policy. A table with dozens of rules, several input columns and overlapping ranges needs more analysis, more test cases and more review rounds before anyone can trust the result. Costs fall into one-time work (modeling the decision, writing tests, setting up review) and recurring work (changing rules, rerunning tests and reviewing edits). Ask any partner for a quote that separates the number of rules, the number of overlaps to resolve and the number of test cases, so you can see which items move the price.
How long does it take to pick the right hit policy for a decision table?
The duration depends on how well the business rules are already written down. If the owners can state, for each input combination, what the answer should be, the policy choice is usually a short design step. If the rules exist only as tribal knowledge or spreadsheets with conflicting entries, most of the time goes into clarifying the rules with the business before any Flowable configuration begins. No fixed duration applies to every table, so ask for a timeline in the written scope that lists the workshops, the review rounds and the testing windows separately.
What do the business and engineering teams need to provide?
The business owners need to supply the decision rules, the expected result for representative cases and sign-off on edge cases such as overlapping ranges or missing inputs. Engineering needs the input and output variable names used by the processes or cases, the Flowable version in use and the rules for how decisions are deployed. Without both sides, the team tends to encode its own assumptions, and the hit policy then reflects those assumptions rather than the business intent. Agree on who owns each rule and who approves changes before the build starts.
Can an internal team choose and implement hit policies alone?
Yes, an internal team with Java and Flowable experience can do this, provided it has a clear picture of the rules and time to test them. The Flowable engines are open source under Apache 2.0, and the documentation covers the DMN engine and its REST API. The harder part is usually not the configuration but the discipline of writing tests per rule and per hit policy, and of keeping rule owners involved. Teams that lack Flowable experience, or that need a fast answer with a documented review trail, often bring in a partner for the design and test phases and keep ownership of the rules in-house.
What happens to the work if the number of overlapping rules grows?
Overlap is the factor that most often changes the scope of the work. Under FIRST or PRIORITY, overlapping rules are resolved by order or priority, so each overlap needs a documented decision about which answer should win. Under UNIQUE, any overlap that matches more than one rule is an error, which means every overlap must be removed before release. Under COLLECT or ANY, overlaps change the shape of the output or require the outputs to agree. As the number of overlaps grows, expect more analysis and more regression tests when rules change, so confirm how the partner handles rule changes after go-live.
Does the choice of hit policy affect testing effort?
Yes. Each hit policy has its own failure modes, so the test plan should include cases that exercise each rule, each overlap and each empty result. FIRST and PRIORITY need tests that prove the right rule wins when several match. UNIQUE needs tests that prove overlaps are caught. COLLECT needs tests that check the list contents and any aggregation. Strict mode behavior also needs its own cases, because a non-matching input can raise an error rather than return an empty result. Ask for the number of test cases to be stated in the quote, along with who writes them and who signs off on expected results.
Does a hit policy decision require a security or compliance review?
It depends on what the decision affects. A decision that approves credit, sets a fee or routes regulated cases carries audit expectations. The record of which rules fired, and why, becomes evidence, so the team should decide early whether DMN execution history will be kept and for how long. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports or certifications, and independent auditors make that determination. Confirm with your compliance lead which controls apply before the hit policy is fixed.
How DeployOpen scopes and delivers Flowable decision tables
DeployOpen treats each Flowable decision table as part of a process or case application, not as an isolated rule file. Hit policy choices are agreed with the business owners and the engineers who will call the decision, then built, tested and documented inside your infrastructure.
How we scope
- Written scope lists each decision table, its inputs, outputs and the hit policy chosen for each one
- Overlap tolerance is agreed with rule owners before any table is built, so UNIQUE or FIRST choices are explicit
- Calling processes and cases are identified up front, including the BPMN business rule tasks and CMMN decision tasks that use each table
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts
How we build
- Decision tables are modeled in DMN files with input and output definitions that match the process variable names
- Strict mode behavior is set and checked for each table so that overlapping or missing rules fail visibly
- Test cases are written per rule and per hit policy, and run against the deployed DMN files in the target Flowable version
- Decision history settings are reviewed alongside the tables to match your audit and storage requirements
How we hand over
- Handover documents each table's hit policy, rule ordering assumptions and the overlaps the design allows
- Test suites and a regression set for rule changes are delivered with the decision files
- Deployment and versioning steps are documented so rule changes can be released without redeploying processes
- Business owners receive a review checklist for future rule edits, including overlap checks under the chosen hit policy
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover
- Retainers can cover re-testing of decision tables when the Flowable engine version changes
- Changes to hit policies or rule sets are scoped in writing before any work starts
- Confirm with DeployOpen which support and testing services apply to your environment before signing a scope
