Visual Mapping GUI

A step-by-step guide to building, saving, and running field mappings without writing any code. The Visual Mapping GUI is available to Developer accounts only.

Overview

The mapper has three panels side by side:

Step 1 — Set up the toolbar

Before loading a document, configure the four toolbar dropdowns at the top of the page:

The Direction toggle (Inbound / Outbound) tells x12port whether you're receiving or sending this document type — it affects how the parsed field tree is labeled.

Step 2 — Load your source document

In the Source Document panel on the left you have two options:

• Paste — switch to the Paste tab and paste your X12, JSON, XML, or CSV directly into the text area.
• Upload File — switch to the Upload tab and drop or browse for a .edi, .x12, .json, .xml, .csv, or .txt file.
• Load from Vault — use the Load from vault… dropdown to pull in a document you've already stored in your Document Vault.

Once your document is in, click Parse Source Fields. The parser will extract every field it finds and list them below the text area with their keys (e.g. BEG.03 or order.header.po_number). Use the filter box to search by name.

Step 3 — Build mapping rules

Each row in the center panel is one mapping rule: a source field → a target field, with an optional transform.

Adding rules

• Click a field in the Source Fields list — it populates the Source Field input of the next rule automatically.
• + Add Rule button — adds a blank row you can fill in manually.
• Quick Templates — pre-built starter rule sets at the bottom of the center panel:
  850 → JSON  |  856 → JSON  |  810 → JSON  |  JSON → 850
  Load a template to get a sensible baseline, then tweak individual rules.
• AI Suggest — paste your source document first, then click ✨ AI Suggest in the toolbar. The AI analyses the document and proposes 5–15 mapping rules. You can accept all at once or pick and choose. Costs 1 AI credit per run.

Transforms

Each rule has a Transform dropdown that modifies the source value before writing it to the target:

Conditional logic (IF / AND / ELSE)

Click the ⚡ IF button on any rule to add qualifier logic. This lets you write rules like: "Map BEG.03 to order_id only IF BEG.02 equals 'SA'".

• IF [field] [operator] [value] — the primary condition
• AND [field] [operator] [value] — add as many extra conditions as needed
• ELSE → [value or source field] — what to write to the target if the condition is not met (optional). The ELSE value also supports transforms.

Common operators: equals, not equals, contains, starts with, is empty, is not empty.

Step 4 — Convert

Once your rules are set and your source document is loaded, click ⚡ Convert Now in the right panel. The output appears in the panel immediately.

• A metadata line above the output shows how many rules were applied and how long conversion took.
• Click Copy to copy the output to your clipboard.
• Check Save output to Document Vault (checked by default) to store the result — then click View in Vault → to open it.

Step 5 — Save your map

Click the map name bar at the top (it says Untitled Map — click to name) and give your project a name. Then click 💾 Save Map in the toolbar. Saved maps are stored to your account and reusable across sessions.

To reload a saved map, click 📂 Maps in the toolbar. The Maps browser shows all your saved projects with their last-modified date. Click a map to load its rules back into the center panel. You can also delete maps from the browser.

Tips

• Start with a Quick Template — even if it's not a perfect fit, it's faster to delete a few rules than to build from scratch.
• Parse before AI Suggest — the AI reads your parsed source document, so parsing first gives it more context and better suggestions.
• Use the filter box — if your X12 document has dozens of segments, type a field name or segment ID in the Source Fields search box to narrow down the list.
• Bidirectional maps — you can save a separate map for each direction. Example: one map for JSON → 850 when sending, another for 850 → JSON when receiving.
• Validate first — if you're working with inbound X12 you didn't generate, run it through the EDI Validator before mapping to catch structural errors early.

Formats reference

AI credits

AI Suggest costs 1 credit per run. Your current credit balance is shown in the toolbar badge next to the AI Suggest button. Buy more credits from Billing — available in packs of 50, 150, and 500.