EDI partner onboarding playbook

Onboarding a new EDI partner is a two-to-six-week cycle depending on complexity, structured in seven repeatable steps. This playbook distils the best practices observed at mature vendors and B2B hubs.

Why a playbook

Without a playbook, every new onboarding reinvents the wheel, forgets a step (which will be discovered in production), accumulates invisible technical debt. A playbook:

Standardises deliverables: each partner goes through the same steps, in the same order, with the same artefacts (TPA, spec sheet, test plan, runbook).
Measures the cycle: each step is dated, time-to-onboard measurable, drifts detectable.
Reduces risk: systematic controls (certificate validation, bilateral tests, rollback plan) avoid startup incidents.
Documents knowledge: onboarding choices are versioned, traceable years later.

Step 1 — Discovery (days 0-3)

Preliminary commercial and technical framing. Actors: account manager on the requesting side, EDI manager on the partner side. Deliverables:

Functional scope: which message types (ORDERS, ORDRSP, DESADV, INVOIC, REMADV…), what expected volumes, what frequency.
Protocol choice: AS2, AS4 PEPPOL, OFTP2, SFTP, REST API. Depends on partner capabilities and regulatory constraints.
Format choice: EDIFACT, X12, UBL, proprietary JSON, other. Often imposed by the dominant partner (mass retailer, automotive OEM).
Target schedule: pilot date, gradual go-live date, full go-live date.
Contact identification: tech lead, ops lead, security on partner side.

Exit criterion: TPA (Trading Partner Agreement) signed or Letter of Intent acknowledged with clear scope.

Step 2 — Spec exchange (days 3-10)

Exchange of detailed technical specifications. For major partners (Walmart, Carrefour, Stellantis, Amazon), retrieval of public or private Implementation Guides. For less formalised partners:

Exact message schema (mandatory segments, specific qualifiers, max lengths, enum codifications).
Business rules (date formats, currency, partner identifiers, references).
Concrete sample files to parse (at least 5-10 examples per message type).
Acknowledgment rules (CONTRL, 997, APERAK, MDN).

Deliverable: versioned partner spec sheet, draft mappings elaborated, test sets collected. Exit criterion: joint technical review accepted by both teams.

Step 3 — Certificate exchange (days 5-15)

Exchange of X.509 certificates required by the transport protocol. For AS2: signing certificate and encryption certificate, typically RSA-2048 minimum, SHA-256 minimum, appropriate EKUs (digitalSignature, keyEncipherment). For AS4 PEPPOL: PEPPOL eDelivery certificate issued by OpenPEPPOL.

Secure exchange mode: never plain email, always dedicated portal or signed exchange.
Verification: valid chain of trust, fingerprints confirmed by phone call (out-of-band).
Validity period: minimum 1 year, ideally 2 years, with planned renewal process.
Registration in the system: certificate recorded in the secret store (Vault, KMS) with expiry alerts at 90d, 30d, 7d.

Exit criterion: certificates exchanged, validated, installed in both gateways.

Step 4 — AS2/AS4 setup (days 10-20)

Technical configuration of the connector. For AS2:

Reception URL (typically /as2/inbox), target partner send URL.
AS2-From / AS2-To identifiers (Trading Partner ID).
Signature algorithms (SHA-256 default), encryption (AES-256-CBC or AES-256-GCM default).
MDN mode (synchronous or asynchronous) and MDN URL if asynchronous.
Compression (zlib if enabled), encoding (binary), content-type.
Retry policy in case of MDN absence.

For AS4 PEPPOL: eDelivery configuration, partner Access Point selection via SMP, ebMS 3.0 parameters, receipt mode (synchronous reply or asynchronous callback).

Exit criterion: validated connectivity (AS2 ping succeeded, AS4 receipt received on empty test message).

Step 5 — Testing (days 15-30)

Critical bilateral validation phase. Three levels:

Mapping unit tests: each mapping passes partner test sets (real or synthetic fixtures). Property-based testing recommended for edge cases.
End-to-end integration tests: real messages exchanged in partner pre-prod environment, MDNs verified, business acks received.
Load tests: verify the hub absorbs the expected volume peak (e.g., 10000 INVOIC batch in 1h).

Deliverable: test report signed by both parties. Exit criterion: all use cases validated, success rate ≥ 95% on test set.

Step 6 — Go-live (days 30-40)

Production switchover. Best practices:

Gradual go-live: start at 10% volume, ramp to 50% on D+3, 100% on D+7. Canary Release pattern applied to onboarding.
Rollback plan: documented procedure to revert to the previous protocol/format in case of blocking incident.
Joint on-call: H+1 on-call setup during the first 7 days, with direct partner hotline.
Internal communication: ops, support, business informed of go-live and watch points.

Exit criterion: 7 days of stable production above the reference SLO.

Step 7 — Monitoring (continuous)

Monitoring is not a post-onboarding step, it is the step that sustains everything that preceded. Indicators to monitor from D+1:

Volume vs forecast: gap > 20% = investigation.
Success rate per message type.
End-to-end latency per flow, vs partner SLO.
MDN time-to-ack, missing-MDN rate.
Dropped messages in DLC.
OTIF per partner.

See the EDI Metrics foundation for indicator details and thresholds.

Foundations

Standards

Flagship messages

Tools