EDI Mapping Specs

EDI Mapping Specs

A mapping spec turns a partner's EDI document into a business object your scripts and apps can use. It says which segment and element carries the PO number, where the line items repeat, and what to call each field.

Find them at Extensions > EDI Mapping Specs. Creating and editing requires DataMagik - Builder.

Why a spec instead of code

Without one, a script reading an 850 has to write segments.find(s => s.tag === "BEG").elements[2] and hope the partner populates BEG03 the way you expect. The knowledge ends up trapped in that script, and onboarding the next partner means copying and editing it. A spec is data: it is versioned, it is testable against a real file, and the same one drives both reading and writing.

Start from a template

DataMagik ships 26 starter mappings, grouped by vertical. Pick one, and the designer opens pre-filled with a sensible layout you then tune to your partner.

The designer

Field paths

A path is SEGMENT[n] for an element and SEGMENT[n][c] for a component. Positions are 0-based, counting the elements after the segment tag. So in BEG*00*SA*PO-48815**20260725:

BEG[0] = "00"          purpose code
BEG[1] = "SA"          PO type
BEG[2] = "PO-48815"    the PO number
BEG[4] = "20260725"    the PO date

Each field also has a type — string, number or date — and a required flag. Default to string: EDI is string data, and a partner sending 00100 for a quantity should not silently become 100 in an audit trail unless you asked for it. Marking a field required means a document that does not carry it is treated as non-conformant and sent to review rather than passed downstream half-empty.

AI discover

Paste a real document into Sample EDI document and press AI discover. DataMagik parses the file structurally — that part is deterministic and always correct — and asks the AI to propose field names and loop boundaries from the segment inventory. You then correct and save.

The names it proposes are its own — a discovered 850 might call the line array lineItems where the starter template calls it lines. Rename anything you would rather match your existing scripts before saving.

Test mapping — a worked 850

This is the part to do before anything else goes live. Paste a document, press Test mapping, and read the object next to the file that produced it.

Given this purchase order:

ISA*00*          *00*          *ZZ*ACMESTEEL      *ZZ*CHUPPCONS      *260725*1200*U*00401*000000101*0*P*>~
GS*PO*ACMESTEEL*CHUPPCONS*20260725*1200*101*X*004010~
ST*850*0001~
BEG*00*SA*PO-48815**20260725~
N1*ST*Chupp Consulting Plant 4~
N4*Columbus*OH*43004~
PO1*1*100*EA*12.50**BP*WIDGET-A~
PID*F****Widget A, zinc plated~
PO1*2*40*EA*31.75**BP*BRACKET-C~
CTT*2~
SE*9*0001~
GE*1*101~
IEA*1*000000101~

the 850-standard starter reports Mapped OK · X12 · envelope valid and produces:

{
  "purchaseOrders": [{
    "poNumber": "PO-48815",
    "poDate": "2026-07-25",
    "parties": [
      { "entityCode": "ST", "name": "Chupp Consulting Plant 4",
        "city": "Columbus", "state": "OH", "postalCode": "43004" }
    ],
    "lines": [
      { "line": "1", "product": "WIDGET-A", "productQualifier": "BP",
        "quantity": 100, "uom": "EA", "unitPrice": 12.5,
        "descriptions": [{ "description": "Widget A, zinc plated" }] },
      { "line": "2", "product": "BRACKET-C", "productQualifier": "BP",
        "quantity": 40, "uom": "EA", "unitPrice": 31.75, "descriptions": [] }
    ]
  }]
}

Note what the spec did beyond copying strings: poDate became a real date, quantity and unitPrice became numbers because those fields are typed, the N1/N4 pair collapsed into one party object, and the PID under each PO1 nested inside its own line rather than floating at the top.

To finish the setup, register the sender as a trading partner with qualifier ZZ and ID ACMESTEEL, and add a routing row for They send us / 850 mapped by this spec.

Using a spec from a script

const result = edi.map(raw, "850-acme");     // apply a saved spec
const tx     = edi.process(raw);             // full pipeline: partner + spec + routing
const specs  = edi.starterSpecs();           // the built-in catalog
const out    = edi.buildMapped(obj, "855-acme");  // the other direction