Decision Trail

Every DMN decision evaluation — whether triggered directly via the API or by a businessRuleTask inside a running process — is automatically persisted. The record captures the exact inputs, which rules matched, and the outputs produced.

Evaluating a decision

curl -X POST https://api.stateway.io/v1/decisions/credit-score-decision/evaluate \
  -H "X-API-Key: sw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"credit_score": 720, "income": 8000}}'

{
  "data": {
    "evaluation_id": "eval_01j...",
    "decision_key": "credit-score-decision",
    "decision_version": 2,
    "decision_hash": "a3f1c2d4e5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "matched": true,
    "rules_matched": ["row_3"],
    "outputs": {
      "approved": true,
      "limit": 50000
    },
    "evaluated_at": "2026-05-19T12:00:00Z"
  }
}

Field	Description
evaluation_id	Persistent identifier for this evaluation record
decision_hash	SHA-256 hash of the DMN source evaluated (see Hash Verification)
rules_matched	Array of rule IDs that matched (e.g., ["row_3"])
outputs	The combined output of the evaluation

Evaluation history

curl "https://api.stateway.io/v1/decisions/credit-score-decision/evaluations" \
  -H "X-API-Key: sw_live_your_key"

{
  "data": [
    {
      "id": "eval_01j...",
      "instanceId": "inst_abc...",
      "elementId": "task_credit_check",
      "decisionKey": "credit-score-decision",
      "decisionVersion": 2,
      "decisionHash": "a3f1c2...",
      "inputVariables": { "credit_score": 720, "income": 8000 },
      "matchedRules": {
        "matched": [{ "rule_id": "row_3", "outputs": { "approved": true, "limit": 50000 } }]
      },
      "outputVariables": { "approved": true, "limit": 50000 },
      "hitPolicy": "UNIQUE",
      "evaluatedAt": "2026-05-19T12:00:00Z"
    }
  ]
}

Filter parameters

Parameter	Type	Description
instance_id	UUID	Return evaluations triggered by a specific process instance
from	ISO 8601	Return evaluations at or after this time
to	ISO 8601	Return evaluations before this time
version	integer	Filter by decision version
limit	integer	Max results (default: 50, max: 100)

Single evaluation details

curl https://api.stateway.io/v1/decisions/credit-score-decision/evaluations/eval_01j... \
  -H "X-API-Key: sw_live_your_key"

Returns the full evaluation record including inputVariables, matchedRules, and outputVariables.

Linking evaluations to process executions

When a businessRuleTask inside a process triggers a DMN evaluation, Stateway records a business_rule.evaluated event in the instance's audit log. The event payload includes the evaluation_id, making it possible to cross-reference the audit log with the decision evaluation record:

{
  "actorType": "engine",
  "action": "business_rule.evaluated",
  "payload": {
    "element_id": "task_credit_check",
    "decision_key": "credit-score-decision",
    "decision_version": 2,
    "decision_hash": "a3f1c2...",
    "evaluation_id": "eval_01j...",
    "variables_snapshot": { "credit_score": 720, "income": 8000 }
  },
  "createdAt": "2026-05-19T12:00:00Z"
}

To trace a specific decision within a process:

1. Get the instance history filtered by action=business_rule.evaluated: GET /v1/instances/:id/history?action=business_rule.evaluated
2. Take the evaluation_id from the event payload.
3. Fetch the full evaluation record: GET /v1/decisions/:key/evaluations/:evaluation_id