Batch eligibility sweeps

Outcome

A batch sweep — verifying eligibility for many members in one cron run — goes out to the partner cleanly, the gateway throttles to the partner's documented capacity, and every member's 271 lands in the right place with no orphaned 270s.

Prerequisites

A trading partner with 270 outbound and 271 inbound capabilities, plus published throughput limits. Familiarity with one-off 270/271 (4.1, 4.2).

Why a batch sweep is different

A real-time 270 is one round trip; the gateway sends one HTTP request and parses one HTTP response. A batch sweep submits a file containing many ST-bounded 270 transactions in one interchange.

The gateway's batch-builder service handles this — see apps/edi-gateway/src/service/batch-builder.ts.

How throttling works

Each partner record carries optional throughput hints (set via /trading-partners/:id → Connection tab → "Batch limits"):

Hint	Default	Effect
max_st_per_interchange	1,000	If a sweep exceeds this, the gateway emits multiple ISA envelopes.
max_interchanges_per_minute	(none)	Rate-limits envelope submission.
max_concurrent_files	1	For partners that reject overlapping files.

The defaults work for most clearinghouses; tighten them when a partner publishes specific limits.

Steps to trigger a sweep

A sweep can be triggered three ways:

Trigger	Where
User-initiated	rcm-app /eligibility/sweeps → + New sweep.
Scheduled	rcm-app /eligibility/sweeps → schedule on cron cadence.
Programmatic	POST /api/v1/eligibility/sweeps (rcm-core).

All three funnel through the same gateway code path. Once the sweep is created:

1. The rcm-core API materializes the member list (filtered by facility / coverage / explicit list).

2. The gateway's eligibility-consumer picks up the sweep event from Service Bus (eligibility.sweep_queued).

3. batch-builder groups members by trading partner (per the routing rules) and composes one or more interchanges per partner.

4. Each interchange is submitted through the partner's normal transport (BATCH_SFTP write, BATCH_REST / BATCH_MFT POST, BATCH_AS2 push, or — rarely for sweeps — REALTIME_REST loop).

5. The 271 file arrives (often a single inbound containing all responses, sometimes split). The response-processor parses the file and dispatches each ST*271 to its originating member context.

6. The sweep's status updates as responses arrive: running → completed. The sweep detail page shows progress.

Steps to debug a stalled sweep

A sweep that stops progressing — partial completion, no new 271s — is debuggable from /transactions:

1. Open /transactions filtered to tx_type = 270, correlation_id = <sweep_id>, status = submitted.

2. Read the row's transport logs — for BATCH_SFTP / BATCH_REST / BATCH_MFT, did the file deliver? For REALTIME_REST, did the partner respond?

3. Check the partner's inbound directory (SFTP) for a 271 file matching the sweep timing. If the file is there but the gateway has not picked it up, the inbound poller may be paused — see 8.2 — Replay & retry.

4. If the partner has not produced a 271, escalate via the partner's normal channel; reference the file by name and ISA13.

Steps to scope a sweep

A sweep against your full active roster can be 50,000+ members — too big for some partners. The sweep configuration page exposes scopes:

Scope	Use case
All active members	Monthly full refresh.
Members on a facility	Facility-by-facility rotation.
Members on a coverage policy	Re-verify one payer's roster.
Upload CSV	List of MRNs (ad-hoc audit).
Members never verified	New members imported but not yet checked.

For partners with strict capacity limits, run a daily slice rather than a single monthly bulk.

Validation

Check	Expected
Sweep advances from running to completed	Yes — typically in minutes (real-time) or hours (SFTP).
Every 270 has a matching 271 by sweep end	Yes (within partner SLA).
Sweep detail page shows per-member outcome (active / inactive / AAA-rejected)	Yes.
Members with EB01 = 6 (inactive) are surfaced as a delta on the rcm-app sweep page	Yes — see Eligibility under the Tenant Manual.

Troubleshooting

Symptom	Cause	Fix
Sweep status stuck on running for hours	Partner throughput slower than expected	Tighten partner batch limits; the next sweep paces correctly.
Some members orphaned (no 271)	Partner's 271 file was incomplete	Replay the failed 270s from the transaction list.
271 file arrives but parses fail	Partner sent a malformed file	Look at the 999 — if the partner's sender flagged it, replay; if not, contact the partner.
Massive AAA rejections on Cannot Identify Subscriber	Member roster has stale member IDs	Run a re-sync from the source feed before sweeping again.

Next

4.4 — 834 enrollment inbound