mountek

Posted on Sep 16

Externalizing Tier-1 Financial Logic via Flowable DMN

#java #microservices #devops #architecture

Hardcoding Tier-1 financial logic—such as credit scoring thresholds, interest rate matrix calculations, anti-money laundering (AML) risk scoring, and fee structures—directly within microservices introduces severe architectural liabilities in modern core banking platform design. When business rules live inside compiled service code (e.g., Java if/else statements or Spring bean components), minor policy adjustments require full software engineering cycles, pull requests, regression test suites, and container redeployments.

Under the Xenon Architecture Standards, modern core banking platforms decouple volatile decision logic from core microservices by externalizing it into declarative Decision Model and Notation (DMN 1.3) engines. This paper analyzes the decoupling architecture using centralized Flowable DMN engines, automated DMN CI/CD promotion pipelines, and strict maker-checker validation workflows for business and risk operators.

💡 Explore the Xenon Architecture Standard For comprehensive architectural blueprints, BIAN service domain mappings, and dual-orchestration integration patterns, visit the official Xenon Architecture Guide. To inspect reference code, infrastructure templates, and open-source banking modules, explore the VecPay-Tech GitHub Organization.

BIAN Service Domain Mapping & DMN Classification

In a Banking Industry Architecture Network (BIAN) alignment, business logic varies by volatility and regulatory oversight. While transactional ledger operations remain static in microservices, Tier-1 financial decisions must be externalized into DMN decision tables.

BIAN Service Domain	Financial Logic	Volatility Level	Deployment Target	DMN Hit Policy
Consumer Advice	Suitability scoring & product eligibility	High	Flowable DMN	`FIRST` (F)
Credit Assessment	Debt-to-Income $DTI$ caps & risk tiering	High	Flowable DMN	`UNIQUE` (U) / `COLLECT` (C)
Payment Execution	ISO20022 fee routing & surcharge matrix	Medium	Flowable DMN	`RULE ORDER` (R)
Position Keeping	Double-entry ledger validation	Low	Hardcoded Microservice	N/A
Fraud Evaluation	Real-time transaction risk scoring	High	Flowable DMN	`COLLECT (SUM)`

Decoupling Architecture: Stateless Flowable DMN Engine

Externalizing business rules isolates microservices from decision policy lifecycles. The microservice acts purely as a stateless Fact Collector, gathering required domain variables (e.g., credit score, collateral value, requested loan amount) and passing them over gRPC or REST to the Flowable DMN Engine.

                     +---------------------------------------+
                     |         Core Microservice             |
                     |  (Loan Origination / Fraud Domain)    |
                     +-------------------+-------------------+
                                         |
                               1. Pass Input Facts
                                  (JSON / gRPC)
                                         |
                                         v
                     +-------------------+-------------------+
                     |       Centralized Flowable DMN        |
                     |           Rule Engine                 |
                     |  (Evaluates FEEL / Decision Tables)   |
                     +-------------------+-------------------+
                                         |
                               2. Return Decision Output
                                  & Execution Audit Trace
                                         |
                                         v
                     +-------------------+-------------------+
                     |       Audit & Compliance Store        |
                     |   (Immutable Decision Snapshot Log)   |
                     +---------------------------------------+

1. DMN 1.3 Decision Table Definition (FEEL Expressions)

The DMN table below calculates the max allowable loan amount and interest markup based on applicant $DTI$ ratio and credit score:

DTI = \frac{\text{Total Monthly Debt Obligations}}{\text{Gross Monthly Income}}

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="https://www.omg.org/spec/DMN/20191111/MODEL/"
             xmlns:flowable="http://flowable.org/dmn"
             id="definitions_credit_tier"
             name="Credit Risk Assessment"
             namespace="http://xenon.banking/dmn/credit">

  <decision id="creditRiskDecision" name="Credit Risk Tiering">
    <decisionTable id="decisionTable_1" hitPolicy="UNIQUE">

      <!-- Inputs -->
      <input id="input_1" label="Credit Score">
        <inputExpression id="inputExpression_1" typeRef="integer">
          <text>creditScore</text>
        </inputExpression>
      </input>

      <input id="input_2" label="Debt To Income Ratio">
        <inputExpression id="inputExpression_2" typeRef="number">
          <text>dtiRatio</text>
        </inputExpression>
      </input>

      <!-- Outputs -->
      <output id="output_1" label="Risk Tier" name="riskTier" typeRef="string" />
      <output id="output_2" label="Interest Markup (%)" name="interestMarkup" typeRef="number" />
      <output id="output_3" label="Approval Status" name="approvalStatus" typeRef="string" />

      <!-- Rules -->
      <rule id="rule_1">
        <inputEntry id="inputEntry_1_1"><text>&gt;= 750</text></inputEntry>
        <inputEntry id="inputEntry_2_1"><text>&lt; 0.35</text></inputEntry>
        <outputEntry id="outputEntry_1_1"><text>"TIER_1"</text></outputEntry>
        <outputEntry id="outputEntry_2_1"><text>0.50</text></outputEntry>
        <outputEntry id="outputEntry_3_1"><text>"APPROVED"</text></outputEntry>
      </rule>

      <rule id="rule_2">
        <inputEntry id="inputEntry_1_2"><text>[650..749]</text></inputEntry>
        <inputEntry id="inputEntry_2_2"><text>&lt; 0.43</text></inputEntry>
        <outputEntry id="outputEntry_1_2"><text>"TIER_2"</text></outputEntry>
        <outputEntry id="outputEntry_2_2"><text>1.75</text></outputEntry>
        <outputEntry id="outputEntry_3_2"><text>"APPROVED"</text></outputEntry>
      </rule>

      <rule id="rule_3">
        <inputEntry id="inputEntry_1_3"><text>&lt; 650</text></inputEntry>
        <inputEntry id="inputEntry_2_3"><text>-</text></inputEntry>
        <outputEntry id="outputEntry_1_3"><text>"TIER_3"</text></outputEntry>
        <outputEntry id="outputEntry_2_3"><text>0.00</text></outputEntry>
        <outputEntry id="outputEntry_3_3"><text>"DECLINED"</text></outputEntry>
      </rule>

    </decisionTable>
  </decision>
</definitions>

2. Microservice Integration via Java SDK

Microservices invoke the stateless DMN engine without coupling to internal rule evaluation paths:

package com.xenon.banking.credit;

import org.flowable.dmn.api.DmnDecisionService;
import org.flowable.dmn.api.DmnExecutionDecisionExecution;
import org.springframework.stereotype.Service;

import java.util.HashMap;
import java.util.Map;

@Service
public class CreditRuleEvaluationService {

    private final DmnDecisionService dmnDecisionService;

    public CreditRuleEvaluationService(DmnDecisionService dmnDecisionService) {
        this.dmnDecisionService = dmnDecisionService;
    }

    public CreditDecisionResult evaluateApplicant(String applicationId, int creditScore, double dtiRatio) {
        // Prepare Fact Payload
        Map<String, Object> inputVariables = new HashMap<>();
        inputVariables.put("creditScore", creditScore);
        inputVariables.put("dtiRatio", dtiRatio);

        // Execute DMN Table by Key
        Map<String, Object> result = dmnDecisionService.createExecutionBuilder()
                .decisionKey("creditRiskDecision")
                .parentDeploymentId("DEP-CREDIT-V2026.3")
                .variables(inputVariables)
                .executeWithSingleResult();

        if (result == null || result.isEmpty()) {
            throw new IllegalStateException("DMN evaluation returned null for application: " + applicationId);
        }

        return new CreditDecisionResult(
                (String) result.get("riskTier"),
                ((Number) result.get("interestMarkup")).doubleValue(),
                (String) result.get("approvalStatus")
        );
    }
}

Automated CI/CD Promotion Pipeline for DMN Models

To guarantee zero regression when business analysts adjust DMN rules, DMN models are treated as Versioned Code Artifacts managed via GitOps.

[ Flowable Modeler ] ──► ( Commit DMN XML ) ──► [ GitHub Repo ]
                                                      │
                                                      ▼
[ Production Engine ] ◄── ( Artifact Promotion ) ◄── [ CI/CD Pipeline (GitHub Actions) ]
                                                      ├─ 1. Static DMN Linting
                                                      ├─ 2. Unit Testing (DMN Engine)
                                                      └─ 3. Replay Production Test Suite

DMN Verification & Automated Testing Pipeline

A GitHub Actions workflow verifies table completeness, checks for overlapping inputs (Hit Policy validation), and executes automated assertion tests prior to artifact promotion:

name: DMN CI/CD Promotion Pipeline

on:
  push:
    branches: [ main ]
    paths:
      - 'dmn/**.dmn'

jobs:
  validate-and-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code Repository
        uses: actions/checkout@v4

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: Validate DMN Syntax & Overlap Rules
        run: |
          ./mvnw dmn-validator:check -Ddmn.dir=./dmn

      - name: Execute DMN Regression Test Suite
        run: |
          ./mvnw test -Dtest=DmnRegressionTestSuite

      - name: Package DMN Deployment Bar
        run: |
          zip -j target/credit-rules-v2026.bar dmn/*.dmn

      - name: Promote Artifact to Enterprise Flowable DMN Registry
        if: github.ref == 'refs/heads/main'
        env:
          FLOWABLE_ADMIN_KEY: ${{ secrets.FLOWABLE_ADMIN_KEY }}
        run: |
          curl -X POST "https://dmn-registry.internal.xenon/dmn-api/development/deployments" \
            -H "Authorization: Bearer $FLOWABLE_ADMIN_KEY" \
            -F "file=@target/credit-rules-v2026.bar"

Maker-Checker Governance & Regulatory Validation

Under Tier-1 financial regulations (e.g., OCC, EBA compliance), business analysts cannot unilaterally push DMN updates directly to production without dual-control operational oversight (Four-Eyes Principle / Maker-Checker validation).

  +--------------------+             +--------------------+             +--------------------+
  |    MAKER ROLE      |             |    CHECKER ROLE    |             |   AUTOMATED CI/CD  |
  | (Risk Analyst)     |             | (Chief Risk Exec)  |             |  PROMOTION STAGE   |
  +---------+----------+             +---------+----------+             +---------+----------+
            |                                  |                                  |
 1. Draft & Simulate Rules                     |                                  |
    in Flowable Modeler                        |                                  |
            |                                  |                                  |
 2. Submit Request for Approval                |                                  |
    (Triggers Flowable CMMN Case)              |                                  |
            +--------------------------------->|                                  |
                                      3. Inspect Champion/Challenger             |
                                         Simulation Diff & Audit Log             |
                                               |                                  |
                                      4. Approve / Reject Change                  |
                                               +--------------------------------->|
                                                                        5. Tag Release & Deploy
                                                                           to Production Registry

Operational Workflow Steps

Maker (Drafting & Champion/Challenger Simulation): The Risk Analyst modifies the DMN decision table within the Flowable Business Engine. The change is tagged as a Draft Challenger Model and executed against historic production transactions to generate a shadow impact report.
Submission & Locking: The Maker submits the DMN change request. The DMN model enters a PENDING_APPROVAL state and is locked against further editing.
Checker (Inspection & Formal Sign-Off): A designated Risk Officer reviews the side-by-side visual diff of the DMN decision table, along with the automated simulation results.
Promotional Signal: Upon formal sign-off by the Checker, the Flowable Engine generates a cryptographically signed approval token and triggers the deployment pipeline into the core banking cluster.

Regulatory Auditability and Explainability

Financial regulators demand full explainability for every credit denial or automated fee application.

When the Flowable DMN engine evaluates a decision, it yields both the business decision payload and a deterministic execution trace containing:

Target DMN ID & Exact Version Number: (e.g., creditRiskDecision:v2026.3.1)
Rules Evaluated: Exact row IDs that satisfied input conditions
Input Fact Snapshot: Unaltered JSON payload containing input parameters
Timestamp & Correlation ID: Linked directly to the central trace context

This architecture guarantees that even if a DMN table changes daily, historical decisions can be accurately replayed and explained for regulatory compliance years after execution.

DEV Community