Submission routing rules

Outcome

A new claim shape (state, payer, claim type, tx type) lands at the right trading partner with the right companion guide, verified via the precedence simulator.

Prerequisites

• CONFIG_MANAGER or PLATFORM_ADMIN.
• Trading partner already exists (2.1).
• Companion guide exists if needed (2.2).

Mental model

rcm_master.submission_routing_rule rows are matched on five dimensions in cascade:

state → payer_type → payer_id → service_line → claim_type / tx_type

claim_type and tx_type are required — every rule names the transaction it routes. The other four dimensions are NULL = wildcard. A rule that pins state='OH' only fires for Ohio; the same rule with state=NULL fires for any state where no Ohio-pinned rule wins.

The resolver picks the rule with the smallest priority value. Among ties at the same priority, the most-specific rule wins (specificity = count of non-null scope dimensions).

Steps — add a rule for a new state

1. Confirm the partner exists. If not, register it via 2.1 first — the routing form lists active partners only.

2. Confirm the companion guide for the (partner, tx type) pair exists. The form preserves an unrecognized companionGuideId if you type it, but the picker shows active guides only.

3. Open Configuration → Routing → New rule and fill the dimensions narrowly.

   Field	Notes
   Claim type	Required (P professional, I institutional).
   Tx type	Required (837P, 837I, 270, 278, etc.).
   State	For state-bound rules. Leave wildcard otherwise.
   Payer type	Use when one rule should cover all MCOs in a state.
   Payer ID	Only for one-payer overrides.
   Priority	10 = high (state-pinned), 50 = mid (payer-type), 100 = wildcard.
   Effective from / to	Optional; leave blank for always-effective.

4. Save → confirm via the simulator (next section) before letting traffic flow.

Verify with the precedence simulator

1. Open Configuration → Routing → Open simulator.

2. Enter the claim shape you expect to flow (claim type, tx type, state, payer type, payer ID, service line).

3. Run Simulate. The panel marks the winning rule Selected and explains every other candidate:

   Reason	Meaning
   LOWER_PRIORITY	Matched but a smaller-priority rule won
   LOWER_SPECIFICITY	Matched at the winning priority but covered fewer dimensions
   SCOPE_MISMATCH	A non-null dimension on the rule disagreed with the simulator inputs (the panel lists which)
   OUT_OF_WINDOW	Simulator's "today" is outside the rule's effective window
   INACTIVE	is_active = false

4. If the wrong rule wins, narrow the intended winner's scope or raise its priority (smaller value). Avoid lowering an existing rule's priority — it's harder to roll back than tightening the new one.

Roll back a misbehaving rule

The detail page exposes Deactivate rather than delete. Always deactivate first; the rule stays in the audit trail and the simulator reports it as INACTIVE. Only delete via SQL after a quarter without incident if you must.

Decision tree — wrong rule fires in production

1. Run the simulator with the exact claim shape from the offending transaction. Note which rule appears as Selected.

2. If Selected is the rule you wanted, the bug is in claim-shape resolution upstream (e.g. claim is missing the state stamp). File a ticket on the claim-build pipeline, not routing.

3. If a different rule won, look at the LOWER_PRIORITY / LOWER_SPECIFICITY neighbours to see which competing rule shadowed yours. Either tighten the intended rule's scope or raise its priority value (smaller wins).

4. If no rule fires (selectedRuleId=null), check the SCOPE_MISMATCH group — usually the new claim shape is missing a dimension every existing rule pins.

Validation

Check	Expected
Simulator with the new shape	Selected = your rule
is_active=true after save	Yes
Real claim flowing through	Lands at expected partner + guide

Troubleshooting

Symptom	Cause	Fix
Picker doesn't show your trading partner	Partner is is_active=false or missing capability	Re-activate, or add the capability via 2.1.
Companion guide not in dropdown	Guide is inactive or for a different tx type	Activate, or pick the right tx type.
Simulator says no rules match	Every rule pins a dimension your simulated shape leaves blank	Add a wildcard fallback at priority 100.
Routing-grid filter "active only" hides your rule	You just deactivated it	Toggle filter; deactivated rules are still selectable for editing.

Cross-references

• Configure a new payer — the rule depends on payer + capability rows.
• Add a state companion guide — picker shows active guides only.

Next

2.6 — Companion guide editor