Routing simulator & precedence debugging

Outcome

When a transaction routes to an unexpected partner — or fails to route at all — you can use the precedence simulator to deterministically identify which rule fired (or didn't), why, and what to change.

Prerequisites

Scope	What it lets you do
edi.routing.read	Open the simulator

Familiarity with how routing rules score and tiebreak (3.3 — Submission routing rules).

Where the simulator lives

/routing page → Precedence simulator panel. Backed by POST /routing/resolve/explain on edi-gateway.

The simulator takes a transaction context as input — not an actual transaction. It is safe to run any time; it never mutates state.

What the simulator returns

The output panel shows:

• Selected rule (the winner) — partner, companion guide, score.
• All candidates sorted by score descending.
• Per losing rule, a per-condition matrix showing which conditions matched and which did not, plus the resulting score.

Common queries

Why is this 837P routing to clearinghouse X instead of state Y?

Inputs:

• Transaction type: 837P
• Payer: state Medicaid (e.g., OH-MEDICAID)
• Program: the specific waiver program
• State: OH

Expected: a state-direct rule should win.

Run the simulator. Outcomes:

Result	Meaning
State-direct rule wins	Working as expected; the misroute happened before the rule existed. Affected transactions need replay.
Clearinghouse rule wins on score	A more-specific rule for the clearinghouse exists — likely the wrong "specific" condition (e.g. payer was specified ambiguously). Inspect.
State-direct rule has score but loses to clearinghouse on tiebreak	Both rules tied; older created_at won. Add a more-specific condition or deactivate one.
State-direct rule does not match at all	A condition is excluding it (typo in payer ID, wrong program code, etc.).

Why is no rule firing?

A transaction stuck "no routing rule":

Inputs: same fields the consumer would have populated.

Expected: at least one rule should match.

Outcomes:

Result	Meaning
Several rules show in candidates	The consumer is using slightly different field values; check the source event's enrichment.
Zero candidates	No rule for this combination exists. Add one or expand an existing rule's conditions.

Why does a tag-based rule never fire?

Tags have weight 1 — the lowest. They lose to any other condition. When a tag-based rule never wins:

• Confirm the tag is the only differentiator between this rule and another. If both rules also share, say, tx_type and payer, the tag is irrelevant.
• Tag-based rules are best for "test envelopes" or "DR" patterns where you want them to lose to anything more specific.

Steps to debug a misrouted transaction

1. Open the misrouted transaction at /transactions/:id. Note its tx_type, partner, and timestamp.

2. Open the source claim / event to capture the inputs the routing context had — payer, program, state, submitter NPI, any tags.

3. Open the simulator → enter those inputs → run. Compare the winner to the actual partner used.

4. If the simulator agrees with reality — the rules were wrong at the time of submission. Adjust the rules; replay the misrouted transaction.

5. If the simulator disagrees — a rule changed between submission and now. Look at the rule edit history (audit log) to see what changed. The intervening edit is the cause.

Steps to test a new rule before saving

1. Compose the new rule in the rule edit form. The simulator panel on the same page accepts a "what-if" mode.

2. Toggle "Include this draft" in the simulator. The simulator runs as if the draft is already saved.

3. Run the simulator with several test contexts — your target context and several adjacent contexts (different state, different program). Confirm:

   • The rule wins for its target context.
   • The rule does not unintentionally win for adjacent contexts.

4. Save when the simulator confirms expected behavior.

Validation

Check	Expected
Simulator returns within 200 ms	Yes — the resolver is in-memory cached.
Per-condition matrix accurately shows match / miss	Yes — verify against your inputs.
What-if mode does not persist the draft	Correct — toggling off the draft is enough.

Troubleshooting

Symptom	Cause	Fix
Simulator returns "no rules in DB"	The rule cache is empty (rare; restart event)	Wait 30s; the cache rebuilds.
Simulator winner differs from actual transaction	Rule changed between submission and now	Inspect rule history; adjust as needed.
What-if mode stays on after closing the page	Browser session cache	Refresh; the toggle resets.
Per-condition matrix shows ✗ on a condition you set	Condition value mismatched (e.g. case sensitivity, leading space)	Re-enter the value; condition matching is exact.

Next

7.1 — The companion guide editor, or revisit Getting Started any time a new teammate joins.