Docs / Learn Mapping

Your first X12 map

An incoming map turns one X12 transaction into the business document your application needs. This guide explains how to read a small map and choose what to learn next. The interactive tutorial provides the editing, running, tracing, and validation practice.

Practice: Map an 850 to JSON Read a small map

Start with the document your application needs

For an X12 850 purchase order, your application might need an order number, a ship-to, and a list of items. Choose those business fields first. Then use a representative sample and the matching X12 version and transaction set to find their source values.

Decide which values are required, which may be absent, and whether each output field holds one value or a list. A ship-to address belongs to one party; each quantity belongs to its own order line. Keeping that context matters more than copying every segment into JSON.

Read one small map

This is the beginning segment from the tutorial's 004010 850 sample. It is an excerpt, not a complete transaction:

BEG*00*SA*PO0001**20260413~

BEG names the segment. In this sample, * separates elements and ~ ends the segment. BEG03 means the third element after the segment name: PO0001.

This complete small map reads that order number from the full transaction and returns a JSON object:

purchaseOrderNumber = ST->BEG(03)
toJson({"purchaseOrderNumber": purchaseOrderNumber})

ST is the selected transaction's root. ->BEG selects its direct BEG child, and (03) reads element 03.
The assignment gives the selected data a name, purchaseOrderNumber, so it can be used in the output.
The braces build a dictionary. The quoted key names the JSON field; the unquoted variable supplies its value.
toJson serializes the dictionary, handling JSON quoting and escaping.

For this sample, the result is:

{"purchaseOrderNumber":"PO0001"}

The order number comes from the input, rather than being hard-coded into the output. It stays text, including any leading zeros. The same gather-then-shape pattern grows into a header, selected parties, and a record for each line. Detailed type and missing-value rules belong in the typed JSON guide.

Practice the core skills in order

Use a desktop browser for the interactive workspace. No account or partner connection is needed for the lessons. Begin with the first chapter, then follow this core sequence; every chapter is also available directly:

Map an 850 to JSONGrow a small map into an order and validate its JSON.
Workspace and X12 foundationsConnect the source document to transaction trees, element definitions, and code lists.
Write reliable incoming mapsSelect the intended records and preserve their values and types.
Test and troubleshoot incoming mapsInspect results, validate output, and diagnose and repair a map.

These lessons use sample data and send no EDI. They teach the authoring workflow; this page remains a short explanation you can return to while reading a map.

Choose the next resource for your task

You do not need to read every reference before mapping. Once the core pattern is familiar, choose the detail your document needs:

Values and JSON explains typed line records, identifiers, missing data, and defaults.
Comparisons covers matching codes and numeric values; arithmetic covers decimal calculations and rounding.
Grouping and ordering covers compatible buckets, line sorting, and grouped summaries; text lists covers packed references and lot codes.
The Mapper Built-ins reference provides signatures and function examples. Use error codes to look up a diagnostic.

To generate X12 from your system's XML or JSON, start the outgoing mapping tutorial directly. That direction uses XSLT or JSLT rather than the incoming mapper language shown above. The outgoing amount reference explains decimal conversion for invoice totals.

When your map works, keep a representative example as a saved test. For partner setup, deployment, and actual traffic, continue with your first partner document.