Designing Rule-Based Subsidy Calculations with Drools
Consider a capital subsidy scheme with a deceptively short specification. The eligible cost is the lower of the quotation amount and the assessed project cost. Applicants in reserved categories receive thirty-five percent of that figure; general category applicants receive twenty-five. No applicant may receive more than the scheme maximum. Four sentences, and a calculation that any developer could write in ten minutes.
The reason it is worth not writing it that way has nothing to do with the arithmetic. It is that every one of those four sentences will change - the rates change with the policy year, the cap is revised, a new category is introduced, a sector gets a different percentage - and each change must be explainable to an applicant who was sanctioned a different amount than they expected.
What a rules engine is actually buying
- Policy expressed in a form a business analyst can read and check against the scheme notification.
- Changes to rates and caps that do not require editing control flow.
- A record of which rules fired, which is what makes a decision defensible.
- Rules for several scheme years coexisting, so historical cases can be recalculated exactly.
That third point is the one that decides it. Nested conditionals produce a number. Rules produce a number and a derivation, and in any process where a citizen or a business can appeal the outcome, the derivation is not optional.
Model the facts before writing any rule
The quality of a rule base is determined almost entirely by its fact model. Three facts cover this domain cleanly, and keeping them separate is what stops the rules from becoming tangled.
| Fact | Role | Mutability |
|---|---|---|
| SubsidyApplication | The input: category, quotation amount, project cost, sector, scheme year | Read only inside rules |
| SchemeParameters | The policy of the day: rates, cap, thresholds | Read only inside rules |
| SubsidyResult | The output being assembled: eligible cost, rate, amounts, trace | Written by rules |
Separating SchemeParameters from the rules themselves is the decision that pays off first. Rates and caps are values, not logic, and treating them as data means a new financial year is a configuration change rather than a release.
One rule, one sentence of policy
Each rule should correspond to a sentence someone could point at in the scheme document. The first is the eligible cost, which is a genuine business rule rather than a technical detail - the scheme deliberately refuses to fund more than was quoted, even if the assessed cost is higher.
rule "base-eligible-cost-is-lower-of-quotation-and-project-cost"
agenda-group "base"
when
$a : SubsidyApplication( quotationAmount != null, projectCost != null )
$r : SubsidyResult( eligibleCost == null )
then
modify( $r ) {
setEligibleCost( $a.getQuotationAmount().min( $a.getProjectCost() ) )
};
$r.trace( "BASE-01", "Eligible cost taken as the lower of quotation and project cost" );
endThe rate rules follow the same shape, one per category, so that adding a category means adding a rule rather than editing an existing branch. Writing them as separate rules also makes the gap visible: if an application arrives with a category nobody anticipated, no rate rule fires, and that is something you want to detect loudly rather than default away.
rule "rate-reserved-category"
agenda-group "rate"
when
$a : SubsidyApplication( category in ( "SC", "ST" ) )
$p : SchemeParameters( )
$r : SubsidyResult( rate == null )
then
modify( $r ) { setRate( $p.getReservedCategoryRate() ) };
$r.trace( "RATE-01", "Reserved category rate applied" );
end
rule "rate-general-category"
agenda-group "rate"
when
$a : SubsidyApplication( category == "GENERAL" )
$p : SchemeParameters( )
$r : SubsidyResult( rate == null )
then
modify( $r ) { setRate( $p.getGeneralCategoryRate() ) };
$r.trace( "RATE-02", "General category rate applied" );
endOrdering without salience spaghetti
This calculation has a strict sequence: establish the eligible cost, apply the rate, then apply the cap. The instinct is to enforce that with salience numbers, and it works until the fourth developer adds a rule with salience 15 because 10 and 20 were taken.
Agenda groups express the same ordering as named phases, which is both readable and stable. The phases are driven from Java, so the sequence of the calculation is visible in one place rather than distributed across rule headers.
KieSession session = container.newKieSession("subsidySession");
session.insert(application);
session.insert(schemeParameters);
session.insert(result);
for (String phase : List.of("base", "rate", "compute", "cap", "validate")) {
session.getAgenda().getAgendaGroup(phase).setFocus();
}
session.fireAllRules();
session.dispose();The cap is a rule, not a clamp
Applying the maximum with a single min call in Java is tempting and loses information. As a rule, the cap records that it applied - which is precisely what the applicant will ask about, because their expected amount and their sanctioned amount differ for a reason that is not obvious from either figure.
rule "cap-at-scheme-maximum"
agenda-group "cap"
when
$p : SchemeParameters( $max : maximumSubsidy )
$r : SubsidyResult( computedAmount != null, computedAmount > $max )
then
modify( $r ) {
setSanctionedAmount( $max ),
setCapApplied( true )
};
$r.trace( "CAP-01", "Computed amount reduced to the scheme maximum" );
endMoney precision is a design decision
Subsidy amounts are money, and money is not a double. Every amount in the fact model should be a BigDecimal, and the rounding policy should be stated once rather than emerging from wherever a division happens to occur.
The rule that avoids most disputes is to carry full precision through the calculation and round exactly once, at the point the sanctioned amount is finalised, with an explicitly chosen rounding mode. Rounding at each intermediate step produces results that are individually defensible and collectively wrong by a few units - which is enough to make a reconciliation against a finance system fail.
Test with scenarios, not assertions
Rule bases are best tested as a table of scenarios with expected outputs, because that table is also a document the business can review. Each row should name what it is proving.
| Scenario | Quotation | Project cost | Category | Expected |
|---|---|---|---|---|
| Quotation is the binding figure | 800,000 | 1,000,000 | GENERAL | 200,000 at 25% |
| Project cost is the binding figure | 1,200,000 | 900,000 | GENERAL | 225,000 at 25% |
| Reserved category rate applies | 800,000 | 800,000 | SC | 280,000 at 35% |
| Cap overrides the percentage | 20,000,000 | 20,000,000 | SC | Scheme maximum, capped flag set |
| Unknown category | 500,000 | 500,000 | OTHER | No rate rule fires - flagged, not defaulted |
That final scenario matters more than the others. A calculation that silently defaults an unrecognised category to the lower rate will produce wrong sanctions quietly for months. A calculation that refuses to produce a result and says no rate rule matched fails visibly on the first case, which is far cheaper.
Return the derivation, not just the number
The output of this calculation should never be a single BigDecimal. It should be a result object carrying the eligible cost, the rate applied, the computed amount, the sanctioned amount, whether the cap bound, and the ordered list of rule codes that fired. That structure feeds the sanction letter, the reviewer's screen, and the appeal file without anyone having to reproduce the logic in a second place.
It also matters for the surrounding process. The figure a rules engine produces usually flows into an approval chain, and an approver who can see why the amount is what it is makes faster and better decisions than one who is shown only the total.
Conclusion
The case for rules here is not that the arithmetic is difficult. It is that policy changes on a schedule the codebase does not control, and that every sanctioned amount must be explainable years later. Keep inputs immutable, put rates and caps in a parameters fact, write one rule per sentence of policy, order the phases explicitly, round money once, and always emit the derivation alongside the number. The next question is how to keep that rule base readable once there are two hundred rules rather than six, which is a maintainability problem with its own answers.