Add a state companion guide

Outcome

A new payer-specific companion guide exists in rcm_master.companion_guide with rules that customize X12 segment / element behavior, and is linked to the appropriate routing rules.

For ongoing rule authoring (the day-to-day UI), see Companion guide editor — this page is the ground-up first-time setup.

Prerequisites

• Payer + trading partner already configured (2.1).
• The payer's published companion guide PDF on hand.

Concepts

A companion guide is a per-(trading-partner, tx_type, version) container for companion-guide rules. Each rule names a target segment (and optionally loop + element / component position) and a rule type that dictates how the applicator transforms the outbound X12 fragment:

rule_type	Effect at apply time
REQUIRED	Validate target exists; emit error if missing.
OPTIONAL	Informational only — no transformation, no validation.
CONDITIONAL	Reserved for downstream semantics. JSON condition preserved for future use.
OVERRIDE	Replace the value at elementPosition with value_override.
SUPPRESS	Filter out every segment whose segment_id matches.
MAP	Pull a value from value_source (dot-notation against runtime context) and write to elementPosition.

Unlike rule sets, companion guides have no DRAFT/PUBLISHED lifecycle — they're either is_active=true (and within their effective window) or not. Versioning is by clone-and-activate.

Steps

1. Open the editor: Configuration → Companion guides → New guide. Pick the trading partner, tx type, version label (e.g. OH-MITS-2026-v1), and a description. Leave Active off if you want to stage rules before activation.

2. Add rules from the payer's PDF. For each rule, set:

   Field	Notes
   Loop	Optional — for navigation only. The applicator matches on segment_id, not loop.
   Segment ID	The X12 identifier (NM1, REF, CLM).
   Element position	0-based — NM108 is elementPosition=7.
   Rule type + payload	Dialog hides irrelevant fields per type. CONDITIONAL requires JSON condition.
   Sort order	Applicator processes in ascending order. Use 100+ for envelope overrides that should run last.

3. Verify with the live preview. The pane re-runs applyCompanionGuide against a built-in 837P/I sample after every save:

   Visual cue	Meaning
   Green-highlighted segments	An OVERRIDE or MAP rule fired
   Strike-through red	A SUPPRESS rule removed segments
   Errors panel populated	A REQUIRED rule's target was missing in the sample

4. Activate the guide. From the detail page, click Activate. The modal lists any active sibling guides whose effective windows overlap — deactivate those unless overlap is intentional. The resolver picks the latest effective_from when multiple guides match, so unmanaged overlap silently shadows the older version.

5. Link to routing rules. Set submission_routing_rule.companion_guide_id on the rules that should apply this guide. The routing rules UI exposes this as a picker.

Break-glass: SQL inserts

When the UI is unavailable, the underlying inserts:

INSERT INTO rcm_master.companion_guide (
  trading_partner_id, tx_type, guide_version,
  description, effective_from, is_active
) VALUES (
  '<trading_partner_id>', '837P', 'EX-2024-v1',
  'Example State 837P Professional Companion Guide',
  '2024-01-01', true
);

-- Example: require rendering provider NPI
INSERT INTO rcm_master.companion_guide_rule (
  companion_guide_id, loop_id, segment_id, element_position,
  rule_type, notes, sort_order
) VALUES (
  '<guide_id>', '2310B', 'NM1', 9,
  'REQUIRED', 'Rendering provider NPI required', 10
);

-- Example: override ISA receiver qualifier
INSERT INTO rcm_master.companion_guide_rule (
  companion_guide_id, segment_id, element_position,
  rule_type, value_override, sort_order
) VALUES (
  '<guide_id>', 'ISA', 7,
  'OVERRIDE', 'ZZ', 100
);

Validation

Check	Expected
companion_guide.is_active	true after activation
Live preview against the sample	Shows expected overrides / suppressions
submission_routing_rule.companion_guide_id	Set on the routing rows that should apply this guide
Test 837 generated for that path	Includes the guide's overrides

Troubleshooting

See Companion guide editor — common errors for the full table.

Next

2.3 — Handle SFTP failure