EDI Management

Platform OperationsGlobal adminLast updated:

This area requires global administrator access in the global tenant context. If you do not have those privileges, you will see a warning message and the content will not be displayed.

EDI Management is where you configure how GEMA processes incoming electronic data interchange (EDI) files received from client SFTP folders, and where you monitor files waiting to be processed or already accepted.

Accessing EDI Management

From the left navigation, select EDI Management. The page loads with three tabs:

  • Mappings — Define and manage EDI mapping configurations.
  • Incoming Files — View files that have arrived via SFTP but have not yet been processed.
  • Accepted Files — View files that have been successfully processed and ingested.

Mappings Tab

The Mappings tab shows a searchable table of all EDI mapping configurations. Each row displays the mapping name, parser type (shown as a colored chip), client, priority, and whether the mapping is Active or Deactivated.

Adding a Mapping

  1. Select Add EDI Mapping in the upper right of the Mappings table.
  2. You are taken to the mapping editor where you can define the mapping configuration.
  3. In the Config panel, choose where the files come from under Data Source, then fill in the mapping name, client, parser, and other settings. No target schema selection is required — the mapping type is inferred automatically from the field mappings you define.

Editing a Mapping

Select any row in the Mappings table, or select the Edit (pencil icon) in the Actions column, to open the full-page mapping editor for that configuration.

In the editor you can modify the mapping rules, parser type, client assignment, priority, and active status. Save your changes when done.

Deleting a Mapping

Select the Delete (trash icon) in the Actions column for the mapping you want to remove. Confirm the deletion in the dialog that appears.

Mapping Editor

Choosing Where Files Come From

In the Config panel, Data Source sets where this mapping gets its files:

  • S3 Files (CSV/Excel) — Files that the client puts in our storage. A Client Name and an Incoming Folder tell GEMA where to look.
  • PharmPix API — Claims pulled from PharmPix. The file controls are hidden for this source.
  • Client SFTP server — Files that GEMA pulls from a server the client runs. GEMA connects on a schedule, copies new files that match the Filename Pattern, and removes each one from the client’s server only after our copy is safely stored.

The Filename Pattern, Parser Type, Parser Settings, and Field Mappings work the same way for our storage and for a client server. The pattern is checked against the file name only, not the folder.

One client can have more than one mapping. For example, you can keep one mapping for files in our storage and a second mapping for files on the client’s own server.

Client SFTP Server Fields

After you choose Client SFTP server, the Client SFTP Server section of the Config panel asks for:

  • Client Name — The name that groups this client’s files once they are pulled in.
  • Host — The hostname of the client’s server.
  • Port — The port number. It starts at 22.
  • Username — The account GEMA signs in with.
  • Remote Folder — The folder on the client’s server that GEMA pulls files from.
  • Host Key Fingerprint (Optional) — The fingerprint of the key the client’s server should show, for example SHA256:.... When you fill it in, GEMA connects only if the server shows exactly that key. When you leave it blank, GEMA connects without checking the server’s key. Clear the field and save to stop checking.
  • SSH Private Key (PEM) and Password — How GEMA signs in. Enter a key, a password, or both. A mapping cannot be activated until one of them is saved.

GEMA never shows a saved key or password again. After you save, a green check appears next to each one that is stored, with the note to leave the field blank to keep it. Type a new value only when you want to replace the saved one.

Test Data on a Client SFTP server mapping lists the files in the saved remote folder whose names match the filename pattern. Save the connection before you open Test Data. Until the connection is saved, the panel asks you to save it first and does not list any files. The list uses the host, port, and sign-in already stored. When Files are encrypted with GPG is on, loading a file decrypts it with the tenant key before the rows appear.

If the fingerprint is filled in and the server shows a different key, GEMA stops before it signs in and the shield bell in the header lights up. See Host Key Mismatch Bell below.

Decrypting Files

For both S3 Files (CSV/Excel) and Client SFTP server mappings, the Decryption section has a Files are encrypted with GPG switch. It is off by default.

When you turn it on, GEMA decrypts each file with the tenant’s key before it reads the file, whether the file arrives in our storage or on the client’s server. The editor shows the tenant’s public key and its fingerprint. Select Copy Public Key and give that key to the client so they can encrypt their files to GEMA. The private key is never shown.

Test Data and Run decrypt the file you select the same way, whether it is in our storage or on the client’s server. Save the mapping with the switch on first, because the test uses the saved setting. If the tenant has no key, or the file was not encrypted to that key, the test stops and says that decryption failed.

If the tenant has no key yet, the editor tells you so. Open the tenant’s Integrations screen and use the GPG Key tab to create one. The link in the message takes you to the tenant.

How Mapping Type Is Determined

There is no target schema dropdown. The mapping type — patient or business units — is inferred automatically from the root-level paths in your field mappings:

  • Business units — if all paths start with carrier, account, or group (e.g. ["carrier", "id"]).
  • Patient — if all paths start with patient-level roots such as patient, insurance, medications, observations, diagnosis, procedures, or authorizations.

A mapping that mixes both types will display an error and cannot be activated. Split it into two separate mappings if needed.

The inferred type is stored automatically on save so the processor can handle the file correctly.

Sync Mode (Business Units only)

When the field mappings target the business unit schema (carrier / account / group paths), a Sync Mode section appears near the bottom of the Config panel:

  • Upsert Only — Adds new business units and updates existing ones. Units absent from the file are left unchanged. Use this for partial files or incremental feeds.
  • Full Sync — delete missing BUs — After upserting, deactivates any active business units (within carriers present in the file) that did not appear in the file. A warning is displayed when this mode is selected. Use only when the file is a complete, authoritative list for the included carriers.

When Full Sync is selected, a Delete safety threshold (%) field appears. This is a circuit breaker: if a single import would deactivate that percentage or more of the business units under the carriers present in the file, all deletes are skipped, the upserts still apply, and the import is flagged with a clear warning. This protects against a truncated or malformed file wiping out a carrier’s tree. The default is 40%. Because deletes are always scoped to carriers present in the file, entirely absent carriers are never touched — offboarding a whole carrier is done through the business unit screens, not by omitting it from a file.

Activation

The Activation toggle is at the bottom of the Config panel, after all other configuration. A mapping cannot be activated until field mappings are defined and parser configuration is set. If conditions are not met, the reason is shown below the toggle.

AI Field Mapping

The Map with AI button analyzes your loaded source data and generates field mappings automatically. If you already have some mappings, the AI uses the inferred schema type (patient or business units). If there are no existing mappings, the AI inspects the source columns itself and chooses the appropriate schema — mapping to carrier/account/group if the file looks like an org hierarchy, or to patient/insurance/claims fields otherwise.

Load test data first using the Test Data button, then click Map with AI.

Schema Reference Panel

In the main editor view, switch the right panel to Schema to view the JSON schema for the inferred mapping type. For patient mappings, this shows the patient record schema. For business unit mappings, this shows the carrier/account/group schema expected for each row. The schema panel updates automatically as you edit field mappings.

Testing a Mapping

Select Run in the editor header to open the test dialog. Select a file or paste sample data, then run the test to see transformed records. For a Client SFTP server mapping, Run lists the files in the saved remote folder and reads the file you select from there, decrypting it first when Files are encrypted with GPG is on. Save the connection first; until then the dialog asks you to save it and does not list any files.

Incoming Files Tab

The Incoming Files tab lists files that have been uploaded to the SFTP and are waiting for EDI intake processing. These files have not yet been run through any mapping.

The table shows each file’s client name (displayed as a chip), file name, file size, and upload timestamp. Select Refresh to reload the list with the latest files from the SFTP source.

If no files are shown, all files have either already been processed or no new files have been uploaded.

Accepted Files Tab

The Accepted Files tab shows files that have been successfully processed and accepted into the system. Use this tab to confirm that a specific file was ingested and to look up processing details.

Host Key Mismatch Bell

If an EDI mapping uses the Client SFTP server data source and you filled in Host Key Fingerprint (Optional) on that mapping, GEMA checks the server’s key before it connects. When the key a client’s server presents does not match the fingerprint on the mapping, GEMA does not connect and no files are pulled from that server.

Administrators who manage EDI see a shield bell in the header, next to the other bell icons. A red number on the bell is the count of client servers whose key did not match. The bell shows no number when every server matches.

Select the bell to open EDI Host Key Mismatches. The list shows one row for each mapping with a problem:

  • Mapping — the name of the EDI mapping.
  • Host — the client server GEMA tried to reach.
  • Expected fingerprint — the fingerprint saved on the mapping.
  • Presented fingerprint — the fingerprint the server showed.
  • Last seen (UTC) — the most recent time the mismatch happened. This time moves forward each time the hourly pull tries again and the key still does not match.

If the client changed their server’s key on purpose, open the mapping, select Config, enter the new value in Host Key Fingerprint (Optional), and save. If you did not expect a change, confirm the new fingerprint with the client before you trust it. Once the server’s key matches again, the row removes itself and the count on the bell goes down. Deleting the mapping also removes its row.