2.8 Ingestion (inbound feeds and mappings)

Outcome

The customer's source systems can deliver members, encounters, eligibility files, and EHR exports into the tenant — via SFTP, real-time push API, or both.

Prerequisites

• 2.7 Rules and modifiers complete.

Two inbound channels

Pick whichever fits the customer:

• SFTP: best for nightly batch from EHRs that already export files.
• Push API: best for low-latency event streams or modern EHR webhooks.

Steps

1. Choose a transport

   Impersonate the tenant → Admin → Ingestion → Feeds → Add feed. Pick:

   • SFTP (inbound): Platform polls a configured SFTP server every N minutes.
   • SFTP (outbound): Platform exposes an SFTP endpoint to which the customer drops files.
   • Push API: Platform issues a bearer key; customer POSTs JSON or X12 to https://api.rcm.medsuite.com/api/v1/ingest/<feed-slug>.

2. Configure the transport

   For SFTP (inbound):

   Field	Value
   Host	customer-sftp.example.com
   Port	22
   Username	the credentials the customer provides
   Auth	password OR private key (write-only — paste once, never displayed again)
   Remote path	/outbound/medsuite
   Cron	*/15 * * * * (every 15 min) or shorthand every-15-min
   Archive on success	yes — moves to /archive after pickup

   For Push API:

   Admin → Ingestion → API keys → Mint key — capture the secret immediately (shown once). Up to 5 active keys per tenant; rotation supported.

3. Have the importer built

   The hand-built mapping editor is retired (#6745). MedSuite builds each feed's importer in the Import Desk (/import-desk, staff with an Import Desk role) from a sample file, reviews it, and publishes it to the feed. A feed loads nothing until its importer is published.

   Once published, the feed's mapping is readable — read-only — from Configuration → Feeds → (feed) → Mapping (read-only), as YAML or field lineage.

4. Test the feed

   For SFTP: drop a small test file in the remote path. After the next poll cycle, the file should appear in Admin → Ingestion → Artifacts with status parsed.

   For Push API:

   curl -X POST https://api.rcm.medsuite.com/api/v1/ingest/acme-members-csv \
     -H "Authorization: Bearer <api-key>" \
     -H "Content-Type: text/csv" \
     --data-binary @sample.csv

5. Set up alerts

   Admin → Ingestion → Feeds → <feed> → Alerts:

   • No file received within N hours: warn at 24, alert at 48.
   • Validation error rate > 5%: alert.
   • Push API quota approaching: warn at 80%, alert at 95%.

Validation

Check	Expected
Test file appears in Artifacts	status parsed
Tenant DB entities exist	row counts match input rows after dedupe
Audit log shows the ingestion	INGESTION_BATCH_PROCESSED events
Push API key works	200 response from POST

Troubleshooting

Symptom	Likely cause	Fix
SFTP poll never fires	Cron disabled at feed level	Edit feed → Toggle 'Active'.
Files arrive but not picked up	Wrong remote path	Inspect with an sftp client; correct the path.
401 from Push API	Key revoked or expired	Mint a new key.
Validation rejects all rows	Mapping schema mismatch	Read the feed's mapping (read-only); have the importer rebuilt in the Import Desk.
Encoding errors on European customer files	UTF-8 BOM / Windows-1252	Have the importer rebuilt in the Import Desk with the right encoding.

Next

2.9 — EDI trading partners