Companion guide editor

Outcome

A new or revised companion guide is authored, previewed against a sample 837, activated, and verified on a real outbound submission.

Prerequisites

• CONFIG_MANAGER or PLATFORM_ADMIN.
• Familiarity with rule-type semantics — see Add a state companion guide for the table.

Author a new guide

1. Open the editor: Configuration → Companion guides → New guide. Choose trading partner, tx type, version label (e.g. OH-MITS-2026-v1), description. Leave Active off to stage rules.

2. Add rules with these fields:

   Field	Notes
   Loop	For navigation only; the applicator matches on segment_id.
   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.
   Sort order	Ascending; use 100+ for envelope overrides that should run last.

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

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

   A REQUIRED-rule error in preview may not be a real-world problem if your production claims always include that segment — but it's a flag to check.

Save as new version

When a payer publishes a guide update, do not edit the live rules in place. Instead:

1. Open the existing guide's detail page and click Save as new version. Supply the new guide_version label (must be unique per trading-partner + tx-type) and an effective_from. Leave Activate immediately off.

2. Edit the new guide's rules to reflect the payer change.

3. Activate when ready. The activate-confirmation 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.

Verify a rule lands on a real submission

After activating, kick a test claim through routing → EDI gateway batch generation → file output. Inspect the resulting 837 file for the change.

Two break-glass commands when the guide appears not to have applied:

# 1. Confirm the resolver picked your guide.
curl -s "http://localhost:3011/edi/companion-guide/<TP_UUID>/837P" | jq

# 2. Re-run the preview against the live guide to see the rule list
#    the applicator received.
curl -s -XPOST "http://localhost:3011/edi/companion-guides/<GUIDE_UUID>/preview" \
  -H 'content-type: application/json' -d '{}' | jq '.data.ruleCount'

If the rule shows in step 1 but not in the outbound file, the rule target may not exist in the live segment array — for example, a REQUIRED rule on 2010BB.NM1 validates only when the build has already emitted that segment. The preview's errors field flags this.

Deactivate a misbehaving guide

UPDATE rcm_master.companion_guide
   SET is_active = false, updated_at = now()
 WHERE companion_guide_id = '<UUID>';

The resolver caches per-(trading_partner, tx_type) for the duration of a single batch build, so deactivation takes effect at the next batch boundary. Confirm with the curl above — the GET should return 404 if no other active guide matches.

Common errors

Symptom	Cause	Fix
409 on guide create	Existing guide has the same (trading_partner, tx_type, guide_version)	Pick a new guide_version label or delete the dead row.
400 ruleType invalid	Typo / case mismatch	Always upper-case (REQUIRED, not required).
Preview shows zero rules applied even after saving	Rule has loop_id set but a typo in segment_id (applicator matches on segment_id only)	Inspect the rule; the column header in the grid is Segment.
Preview errors list a missing segment that does exist on real submissions	Built-in sample 837P doesn't include every loop the guide expects	Provide a { segments: [...], context: {...} } POST body to the preview endpoint with a real-shape claim, or verify on a real outbound file instead.
"I activated the new guide but nothing changed"	Older version is still active and has a later effective_from	Deactivate the older version.

Boundaries

• No DRAFT/PUBLISHED workflow. Approval is by activate-time policy, not by lifecycle gate. If your compliance posture requires approval routing, file a ticket — do not retrofit with is_active=false as a "draft."
• The applicator is segment-id-scoped. Setting a loop_id on a rule is for UI navigation only — it does not narrow the applicator's match. A rule on NM1 matches every NM1 in the X12 document.
• Rule order matters. The applicator walks rules in sort_order ascending, so a later OVERRIDE can clobber an earlier MAP. Use the preview's left/right diff to confirm final state before activating.

Validation

Check	Expected
is_active=true post-activation	Yes
Preview against sample	Shows expected rule effects
Outbound 837 from real claim	Includes overrides / suppressions
Sibling-guide overlap	None (or intentional)

Cross-references

• Add a state companion guide — first-time setup view.
• Submission routing rules — link the guide to specific routing rows.

Next

2.7 — Trading partner credential vault