Edi Engineer

EDI Engineer

When to Use

• Design or operate B2B EDI integrations—inbound/outbound pipelines, partner profiles, replay
• Map canonical business objects (order, shipment, invoice, inventory) to X12 or EDIFACT segments and loops
• Implement partner-specific rules from implementation guides, companion guides, and trading partner agreements
• Configure validation—syntax (X12 envelope/segment rules, EDIFACT UNB/UNH), implementation conventions, SNIP/business edits
• Build acknowledgment and exception flows—997/999, CONTRL, APERAK, negative acks, operator queues
• Onboard trading partners—certification, test environments, cutover, production monitoring
• Choose and operate transport—AS2 (sign/encrypt, MDN), SFTP/FTP, VAN mailbox patterns at integration level
• Handle healthcare EDI variants (834 enrollment, 835 remittance, 837 claims) as structured messaging—never embed PHI in docs or logs
• Implement idempotency, deduplication, and reconciliation between EDI documents and ERP/WMS/OMS state

When NOT to Use

• Generic REST/GraphQL or event-bus integration with no EDI standards or segment mapping → senior-software-engineer
• WMS waves, pick paths, RF scanning, slotting, or warehouse operational logic → wms-developer
• Supply chain strategy, sourcing, forecast policy, or supplier QBRs without EDI implementation → supply-chain-manager
• SOC/ISO/HIPAA compliance program, audit evidence, and control attestation without EDI engineering → compliance-engineer
• VRP, MIP, scheduling, or solver-based routing optimization → operations-research-algorithm-developer
• Penetration testing or offensive security of partner endpoints → penetration-tester
• Legal review of trading partner contracts → commercial-counsel

Related skills

Core Workflows

1. Scope and boundaries

Define standards in scope (X12 version, EDIFACT release), transaction sets, direction, systems of record, and PHI handling.

See `references/edi_engineer_scope.md`.

2. Standards and message families

Select transaction sets, envelopes, and version/agency identifiers.

See `references/standards_x12_edifact.md`.

3. Mapping and translation

Build canonical models, segment/loop maps, code lists, and transformation rules.

See `references/mapping_and_translation.md`.

4. Validation and acknowledgments

Layer syntax, partner, and business validation; define ack and exception paths.

See `references/validation_and_acknowledgments.md`.

5. Transport and partner onboarding

Configure connectivity, certificates, mailboxes, certification, and cutover.

See `references/transport_and_partner_onboarding.md`.

6. Testing, monitoring, and reconciliation

Certification suites, observability, replay, and financial/operational tie-out.

See `references/testing_monitoring_and_reconciliation.md`.

Outputs

• Partner profile — IDs, qualifiers, versions, allowed transaction sets, test vs prod endpoints
• Canonical data model — entities, keys, UOM, dates, references, allowance/charge patterns
• Mapping specification — segment/loop map, conditions, code conversions, sample in/out pairs
• Validation matrix — syntax, IG, SNIP/business rules, severity, remediation owner
• Acknowledgment design — 997/999 or CONTRL/APERAK triggers, negative ack content, SLA
• Runbook — stuck interchange, MDN failures, duplicate control numbers, reconciliation breaks
• Test pack — positive/negative cases, volume samples, certification sign-off checklist

Principles

• Map EDI → canonical → domain systems; avoid EDI-shaped tables in core business schemas
• Treat every interchange as idempotent—control numbers, message refs, payload hash, dedupe store
• Fail closed on validation; route exceptions to quarantine with actionable codes—not silent drops
• Separate test and production profiles; never cross-wire ISA/GS or UNB interchange IDs
• Log metadata only for healthcare payloads—no member names, diagnoses, or claim detail in tickets
• Plan reconciliation jobs comparing document totals to ERP/WMS open items and payments
• Document partner drift—IG revisions, segment usage changes, and coordinated version upgrades

EDI engineer scope

Table of contents

1. Role boundaries 2. In scope 3. Out of scope 4. Systems of record 5. Lifecycle phases 6. Healthcare variant 7. Deliverables checklist

Role boundaries

The EDI engineer owns how structured B2B messages move, validate, transform, and reconcile between trading partners and internal applications. Own the integration layer: parsers, mappers, validators, routers, ack generators, transport adapters, and operational tooling—not corporate supply chain strategy, warehouse UI workflows, or generic API design unless EDI is the payload contract.

Coordinate with:

• ERP/OMS/WMS teams for canonical object definitions and posting rules
• Infrastructure/security for certificates, AS2 endpoints, SFTP keys, secrets rotation
• Partner managers for trading partner agreements, SLAs, and certification windows

In scope

Out of scope

• Building WMS pick/wave logic or RF screens → wms-developer
• Defining supplier scorecards or network design without EDI → supply-chain-manager
• Writing microservices with no EDI contract → senior-software-engineer
• HIPAA security risk assessment program → compliance-engineer
• Mixed-integer routing models → operations-research-algorithm-developer

Systems of record

Assign explicitly per entity:

EDI layer must not become SOR for business truth—persist canonical documents and interchange audit, then post to domain systems with idempotent keys.

Lifecycle phases

1. Discover — IG, sample files, transaction frequency, direction, code lists 2. Model — canonical schema, keys, UOM, dates, references, taxes/charges 3. Map — segment rules, loops, conditions, defaults, code conversions 4. Validate — syntax + partner + business matrices 5. Connect — transport, certs, test mailbox, certification 6. Test — unit maps, partner cert, negative cases, volume soak 7. Cutover — parallel run, reconciliation, rollback triggers 8. Operate — monitor, replay, IG change management, periodic recon

Healthcare variant

834 (enrollment), 835 (payment/remittance), 837 (claims) share X12 mechanics but impose stricter privacy and companion-guide complexity.

• Treat PHI as classified data: redact in logs, tickets, and skill outputs
• Reference companion guides and payer-specific edits without copying member or clinical content
• Coordinate HIPAA technical safeguards with compliance-engineer; do not substitute legal attestation

Deliverables checklist

• [ ] Partner profile (ISA/GS or UNB IDs, versions, charset, test/prod)
• [ ] Transaction set inventory with direction and frequency
• [ ] Canonical model and mapping spec with samples
• [ ] Validation rule catalog with severity and owner
• [ ] Ack and exception workflow diagram
• [ ] Transport runbook (cert rotation, MDN failures)
• [ ] Certification sign-off and cutover plan
• [ ] Reconciliation job definitions and tolerance thresholds

Mapping and translation

Table of contents

1. Canonical model first 2. Mapping layers 3. Segment and loop patterns 4. Code lists and conversions 5. Dates, quantities, and UOM 6. Allowances and charges 7. Direction-specific rules 8. Mapping specification template

Canonical model first

Define canonical documents independent of X12 or EDIFACT:

Use stable business keys: partnerId, poNumber, lineNumber, sku, shipmentId, invoiceNumber. Map EDI references (BEG03, RFF, REF) into named fields—not opaque segment dumps.

Mapping layers

1. Parse — raw interchange → typed segment tree (validated syntax) 2. Normalize — trim, timezone, decimal scale, default missing optional segments per IG 3. Transform — segment tree ↔ canonical (rules engine or compiled maps) 4. Enrich — lookup SKU cross-ref, ship-to resolution, org hierarchy 5. Publish — canonical → ERP/WMS API or outbound generator

Keep layers testable in isolation with golden files per layer.

Segment and loop patterns

X12 loops (examples):

• PO1/N9/SCH — line, reference, schedule
• HL hierarchy — shipment → order → pack → item (856)
• IT1/TDS — invoice lines and totals

EDIFACT loops — LIN, QTY, PRI, RFF, NAD, TDT, PAC segments grouped by message structure.

Rules:

• Document loop entry/exit conditions (e.g. HL03 code determines level)
• Handle optional segments with explicit defaults vs reject
• Support repeating parties (N1/N3/N4, NAD) via role codes (BT, ST, SF, BY)

Code lists and conversions

Maintain conversion tables versioned per partner:

Never hardcode partner-specific qualifiers in shared maps—use partner profile overlays.

Dates, quantities, and UOM

• Parse CCYYMMDD vs YYMMDD per IG; store UTC instants with source timezone metadata
• Quantities: respect integer vs decimal per UOM; reject ambiguous floats
• Catch-weight: separate ordered vs shipped weight fields in canonical model

Allowances and charges

Map SAC, ALC, TAX segments into canonical AllowanceCharge lines with:

• Type (allowance vs charge)
• Basis (percent vs amount)
• Agency/qualifier codes
• Link to header vs line

Required for invoice match and deduction management.

Direction-specific rules

Mapping specification template

For each transaction set document:

## 850 → PurchaseOrder (Partner: ACME, 5010)

### Header
| Canonical field | Segment | Element | Rule |
|---|---|---|---|
| poNumber | BEG | BEG03 | required |
| poDate | BEG | BEG05 | CCYYMMDD → date |

### Line loop PO1
| lineNumber | PO1 | PO101 | sequence |
| sku | PO1 | PO107 | via xref table partner_sku |

### Conditions
- If BEG02 = '00' then original PO; '05' replace — call change-order handler

### Samples
- inbound: samples/acme_850_001.x12 → expected: golden/acme_po_001.json

Store samples under version control; run in CI on map changes.

Standards: X12 and EDIFACT

Table of contents

1. Envelope hierarchy 2. Common X12 transaction sets 3. Common EDIFACT messages 4. Version and agency identifiers 5. Delimiters and character sets 6. Control numbers and uniqueness 7. Healthcare X12 (concept)

Envelope hierarchy

X12 (ANSI)

ISA (interchange) → GS (functional group) → ST (transaction set) → segments

• ISA/IEA — interchange control; sender/receiver IDs, standards ID, control number
• GS/GE — functional group; application sender/receiver, version/release, group control number
• ST/SE — transaction set; ST01 = transaction set ID (e.g. 850), control number

EDIFACT (UN)

UNB (interchange) → UNG (optional group) → UNH (message) → segments → UNT → UNZ

• UNB/UNZ — interchange header/trailer; syntax version, partners, control reference
• UNH/UNT — message header/trailer; message type (e.g. ORDERS), reference number
• UNG/UNE — optional functional grouping for batching related messages

Common X12 transaction sets

Retail and grocery often add 894/895/816 and require SNIP validation profiles—call out in partner profile.

Common EDIFACT messages

EDIFACT uses composite data elements and coded lists (e.g. ISO country, UN/ECE units)—map via explicit code tables, not ad hoc strings.

Version and agency identifiers

Capture in partner profile:

Never assume one global version—partners drift on different releases per document.

Delimiters and character sets

X12 uses configurable element, segment, and subelement separators in ISA (positions 104–105 and implied conventions). EDIFACT uses UNA or service-string advice defaults.

• Document chosen delimiters in partner profile
• Parser must read ISA/UNA before tokenizing—do not hardcode * and ~ without verification
• Support UTF-8 where partners require multibyte; validate charset in UNB if EDIFACT

Control numbers and uniqueness

Implement allocator + dedupe store: reject or quarantine duplicates; allow partner-specific reuse rules only when documented.

Healthcare X12 (concept)

Use same envelope/mapping discipline; add payer-specific edits and stricter audit. Defer compliance program design to compliance-engineer.

Testing, monitoring, and reconciliation

Table of contents

1. Test pyramid 2. Golden files and fixtures 3. Certification testing 4. Production monitoring 5. Replay and idempotency 6. Reconciliation 7. Incident response 8. Metrics and SLAs

Test pyramid

Fail builds on any golden diff unless explicit snapshot update reviewed.

Golden files and fixtures

Organize:

tests/
  inbound/x12/850/partner_acme/happy_path.x12
  expected/canonical/po_acme_001.json
  inbound/x12/850/partner_acme/missing_po1.x12
  expected/errors/syntax_missing_po1.json

• Strip dynamic timestamps in comparators or normalize in test harness
• Include edge cases: empty optional loops, max repetitions, unicode, leading zeros
• For healthcare samples, use synthetic data only—no real PHI

Certification testing

Track partner case matrix:

Record environment (test ISA IDs), software version, and map version on sign-off PDF.

Production monitoring

Alerts (examples)

• Interchange received but no ack within SLA
• MDN failure rate spike
• Quarantine depth > threshold
• Map exception rate by partner
• Reconciliation break count

Dashboards

• Volume by partner / document type / hour
• Latency: receive → post → ack
• Error taxonomy: syntax vs business vs posting

Log interchange control numbers and canonical IDs—never full PHI payloads in healthcare.

Replay and idempotency

Persist:

• Raw payload (encrypted object store)
• Parsed representation
• Canonical document
• Posting result and external ERP keys

Replay rules

• Same control number + partner + direction → dedupe unless flagged forceReplay by ops
• Replay from canonical when ERP was down—skip transport re-fetch
• Re-generate outbound only if partner accepts new control numbers

Reconciliation

Define tolerance (qty, amount, timing) per partner; escalate breaks above threshold.

Three-way match (concept)

PO (850) → ASN (856) → Invoice (810): align line refs, shipped qty, price, allowances before auto-approve.

Incident response

Document runbooks per partner for hypercare weeks after cutover.

Metrics and SLAs

Partner-facing SLAs often include:

• Ack within N minutes
• Document processing within N hours
• Uptime of AS2 endpoint

Internal SLOs:

• 99.9% successful syntax processing
• < 0.1% unrecoverable quarantine without owner
• Mean time to replay < 30 minutes for sev-2

Review metrics in monthly partner QBRs with operations and account teams.

Transport and partner onboarding

Table of contents

1. Transport patterns 2. AS2 essentials 3. SFTP and file-based 4. VAN and managed networks 5. Certificates and secrets 6. Partner onboarding phases 7. Certification and cutover 8. Partner profile schema

Transport patterns

EDI engineer owns handoff to parser—file or MIME body plus metadata (filename, AS2 Message-ID, received time).

AS2 essentials

• Endpoints — separate URLs for test/prod; document IP allowlists if used
• Signing / encryption — partner cert, own cert, algorithm suite (SHA-256, AES-256)
• MDN — synchronous vs asynchronous; signed MDN expectations
• Compression — optional; verify partner support
• Duplicate detection — use AS2 Message-ID + payload hash

Failure modes

• Certificate expiry → proactive rotation calendar
• MDN timeout → retry policy; do not double-post business documents
• 413/oversize → split at functional group only when partner permits

SFTP and file-based

Conventions to document per partner:

• Directory layout — /inbound, /outbound, /archive, /error
• Naming — {partner}_{doctype}_{timestamp}_{control}.edi
• Encoding — ASCII vs UTF-8; BOM handling
• Completion signal — .done file vs rename vs zero-byte trailer

Implement atomic pickup (rename to .processing) and virus scan hook if policy requires.

VAN and managed networks

• ISA IDs / UNB partners — production vs test qualifiers
• Mailbox / interconnect — route tables maintained with VAN ops
• Billing and traffic reports — reconcile volume with internal metrics

Abstract VAN behind same ingest service as AS2/SFTP to reuse validation and mapping.

Certificates and secrets

• Store private keys in HSM or secrets manager—not repos
• Track expiry 90/30/7 days; automate renewal where possible
• Maintain trust stores per partner; pin prod certs separately from test
• Rotate SFTP keys with parallel install window

Coordinate with information-security-engineer for cipher policy; do not weaken TLS for convenience.

Partner onboarding phases

1. Kickoff — transaction sets, direction, volume, SLAs, contacts 2. IG collection — version, errata, sample files, code lists 3. Profile build — IDs, delimiters, transport, cert exchange 4. Map development — canonical maps + validation pack 5. Unit test — golden samples internal 6. Certification — partner test mailbox, scripted cases 7. Parallel production — shadow or dual-write with reconciliation 8. Prod cutover — freeze window, hypercare, rollback criteria

Certification and cutover

Certification checklist

• [ ] All required transaction sets in/out
• [ ] Positive and negative scenarios signed by partner
• [ ] 997/CONTRL behavior verified
• [ ] Volume test (peak file size / count)
• [ ] Clock skew and timezone cases
• [ ] Duplicate interchange handling

Cutover

• Switch transport profile from test to prod IDs
• Run reconciliation on first 24–72 hours hourly
• Keep rollback — revert DNS/AS2 URL and replay from canonical backlog if needed

Partner profile schema

Minimum fields:

partnerId: ACME
standards:
  x12:
    version: "005010"
    isa:
      senderId: "SENDER"
      senderQual: "ZZ"
      receiverId: "RECEIVER"
      receiverQual: "ZZ"
transactions:
  - id: "850"
    direction: inbound
    mapVersion: "3.2.0"
transport:
  prod:
    type: as2
    url: https://...
    signingCert: ref://secrets/acme_sign
validation:
  ig: "ACME_850_IG_v4.pdf"
  snipProfile: retail_grocery_7.2
ack:
  generate997: true
  slaMinutes: 15

Version profile with application releases; support per-partner feature flags for gradual map rollout.

Validation and acknowledgments

Table of contents

1. Validation layers 2. Syntax validation 3. Implementation guide rules 4. SNIP and business edits 5. Functional acknowledgments 6. Application advice and exceptions 7. Quarantine workflow 8. Severity model

Validation layers

Apply in order; short-circuit only when partner requires early ack:

Syntax validation

X12

• ISA length and fixed fields; GS/ST nesting; SE segment count match
• Valid segment IDs; element length per dictionary; mandatory elements present
• Composite elements and repetition separators respected

EDIFACT

• UNB/UNH/UNT/UNZ consistency; message reference uniqueness within interchange
• Service string advice; release character handling

Return machine-readable error lists (segment, position, element, code) for ack generation and ops UI.

Implementation guide rules

Partner implementation guides (IGs) override general standards:

• Which segments are mandatory vs optional
• Allowed code values and qualifiers
• Maximum loop iterations and trailer requirements
• Usage notes (e.g. single GS per ISA vs multiple)

Version IGs in partner profile; run validation against IG version + effective date.

SNIP and business edits

SNIP (retail grocery/supply chain) profiles add cross-segment business rules—e.g. PO line totals, allowance consistency, 856 HL structure.

Implement as rule packs separate from syntax:

• Configurable per partner/industry
• Each rule: ID, description, severity, remediation hint
• Support waivers with expiry for cert periods only

Functional acknowledgments

X12 997 / 999

• 997 — functional accept/reject at group or transaction level (AK1/AK2/AK5)
• 999 — implementation-level errors with IK segments (5010+)

Generate promptly when partner SLA requires; include accurate AK5/IK5 codes.

EDIFACT CONTRL

• Report syntax and service-level acceptance for UNH/UNG/UNB
• Link to original control references for partner correlation

Timing

• Define SLA (e.g. ack within 15 minutes of receipt)
• Async generation acceptable if interchange already persisted with status received

Application advice and exceptions

When syntax passes but business posting fails:

• X12 824/864 or partner-specific APERAK (EDIFACT) for application-level errors
• Include canonical document ID, error code, field path, partner reference numbers

Distinguish:

• Reject — do not process; partner must resend
• Accept with errors — partial line accept; document remaining exceptions
• Hold — await master data fix then replay from canonical store

Quarantine workflow

Receive → Syntax OK? → Map → Business OK? → Post
                ↓ no          ↓ no
            997/CONTRL    Quarantine queue
                              ↓
                    Ops: fix map / master data / contact partner
                              ↓
                         Replay (idempotent)

Quarantine record must store: raw payload hash, parsed tree, validation report, partner ID, timestamps, assignee, resolution code.

Severity model

Document partner-specific overrides—some retailers treat warnings as fatal.