ModernEDI

Docs / Optional Verification / Supplier Example

One order, an optional acknowledgment, a shipment, and an invoice

The retailer orders 10 units of ITEM-A at $12.50 and 10 units of ITEM-B at $25.00. The supplier ships the complete order and invoices $375.00. This example checks the business details across the documents, not just whether their totals happen to match.

Mappings work without scenarios or Git.

Add this conversation when you want extra verification. Your application still decides when to acknowledge, ship, and invoice. Creating a draft or running the local tests sends nothing.

What the conversation means

  1. 850: receive the order.PO-EXAMPLE-1001 contains two distinct supplier item identifiers, units, quantities, prices, and USD currency. The incoming Mapper script turns it into JSON for your application.
  2. 855: optionally acknowledge it.Set acknowledgmentCount to 1 when a business acknowledgment is expected, or 0 when the agreement does not require one. An expected 855 must name this PO, arrive within two days, and use BAK02 AK (acknowledge, no detail or change). Rejection and acceptance with changes are outside this full-fulfillment example.
  3. 856: ship the whole order.SHIP-1001 must name the PO and arrive within seven days of the order. Each item/unit combination and quantity must match. The wrong allocation between items does not pass, even when the total quantity is unchanged.
  4. 810: invoice that shipment.The invoice names both the PO and SHIP-1001 (REF qualifier SI in this sample). It follows the ASN within seven days, and is within 30 days of the order. Items, units, quantities, unit prices, currency, and the total must agree.

The 855 is checked independently against the order; this example does not require it to arrive before the ASN. A missing expected 855 keeps the conversation pending until its deadline, then fails. A run configured for no 855 does not silently accept an unexpected one. Choose that expectation before starting, not after seeing the result.

The definition uses an existing conditional path, called a branch, for the 855. After the order's facts are available, the runtime records the orderObserved checkpoint and selects that path only when acknowledgmentCount is 1. That checkpoint is an internal point in the verification process, not another document or an extra button you must click. Shipment and invoice checks remain required in either case.

855 is not 997/999. The 855 expresses business acceptance of the order. BAK02 AC instead means acknowledgment with detail and change; it does not pass this unchanged-order example. See the 855 acknowledgment-code reference and follow your partner’s permitted codes. A functional or implementation acknowledgment concerns EDI processing, and an AS2 MDN concerns transport receipt. This example checks document facts; it does not require mapping-success, MDN, or 997/999 evidence. Add the existing assurance requirements when those are part of your partner agreement.

The maintained example files

These are synthetic X12 004010 examples with Test envelopes (ISA15=T). They contain no credentials or live partner addresses and are not a retailer's implementation guide.

The ASN uses a simple shipment → order → item hierarchy. Its CTT01 counts all four HL segments, including shipment and order, not just the two items. See the 856 transaction-set notes for that distinction; this sample does not implement Walmart's complete partner requirements.

Adapt it in the browser

  1. Start with your partner and maps.Use your existing partner, or configure an agreed test partner. The source examples use X12 Mapper for incoming 850 and JSLT for outgoing 855, 856, and 810. Open the sample inputs and expected outputs from the saved case files in Mapper's Tests workflow. Enable generated-X12 validation for outgoing cases. Select the appropriate 004010 transaction tree, adapt to your partner guide, review, and deploy the maps. The outgoing maps produce body segments; ModernEDI generates the envelopes and control numbers.
  2. Create the optional definition.In Mapper's scenario tools, choose New scenario definition → Supplier order fulfillment. The editor supplies a fresh custom identity. Validate and publish it. If copying the public JSON instead, change its reserved modernedi.examples namespace first.
  3. Bind your configuration.Use New scenario binding and select the published definition. For this unchanged example, the form defaults to the supplier workspace actor and Test traffic. Choose the retailer partner and corresponding current maps. With a resolved 004010 syntax context, select Fill empty facts from example for each step, review the expressions, then validate and apply. Existing expressions are preserved; no placeholder partner or map IDs are copied. If you changed the graph, adapt the downloadable expressions yourself.
  4. Review identifiers instead of copying them blindly.Partner 42 and mapping IDs 101–104 in the downloaded binding are placeholders. Its definition hash is valid only for the supplied graph with namespace example, key supplier-order-fulfillment, and version 1.0.0. The binding form selects the actual published identity and hash. Do not invent a hash or use a file checksum. The sample explicitly selects 004010; automatic resolution remains available when appropriate for your own maps.
  5. Start with the intended 855 expectation.Use {"acknowledgmentCount": 1} or {"acknowledgmentCount": 0}. The binding still declares all four steps and resolves their dependencies even when the run expects no 855. If you permanently remove the 855 from your custom definition, also remove its transition, assertion, branch, parameter, and the orderObserved checkpoint and pipeline stage, then create a matching binding.
  6. Collect fresh, authorized evidence.Arrange Test traffic with the partner and attach the actual persisted 850, optional 855, 856, and 810 transactions to the run. Existing eligibility and frozen-configuration checks apply. Local fixture files are not live evidence and cannot be submitted as arbitrary scenario observations. Your application sends outgoing documents through the ordinary mapping/send workflow; the scenario does not send them for you.

Do not send these synthetic files to a real trading partner without agreement. Test traffic uses the same deployed maps as Production, not a separate test mapping deployment. The traffic guide explains the configuration and evidence boundaries.

Mapper does the document work; the scenario compares the results

A binding fact can already use more than a segment selector. It can use ordinary Mapper collection operations, arithmetic, and Boolean expressions. For example, the order's line total is:

sumOf(line in ST->PO1 => round(toNumber(line(02)) * toNumber(line(04)), 2))

The example rounds each USD line amount to two decimals before summing. TDS01 is an X12 implied-decimal amount with two decimal places. Mapper selects its wire text, so the binding uses toNumber(ST->TDS(01)) / 100 to compare TDS*37500 as 375.00 dollars.

To compare arbitrary item order, each binding expression sorts its document's lines by a JSON-encoded pair of supplier item identifier and unit. It then extracts a list of keys, a list of numeric quantities, and (where present) a list of numeric prices in that same order. The scenario compares the aligned lists and rejects duplicate keys. JSON encoding avoids ambiguous string concatenation; numeric facts compare numerically, so 10 and 10.00 agree.

This is reuse of the existing Mapper language, not a new expression engine. Each fact expression reads one bound document and returns one typed value or scalar collection, with bounded execution and source evidence. Arbitrary multi-statement programs across several documents are not currently a scenario assertion type. A future extension should retain those limits and evidence rather than turn verification into a general script runner.

What you can and cannot infer from a pass

  • One full shipment and one invoice. Use the partial-shipment and backorder extension for a two-part fulfillment. Multiple orders in one ASN, consolidated invoices, changes, substitutions, and cancellations need different rules. A partial shipment fails this full-shipment example; it is not automatically an invalid business transaction.
  • One row per item/unit. Repeated item/unit rows within a document are rejected, not silently combined. The partial-shipment extension demonstrates per-item accumulation across several documents.
  • Specific identifier positions. The sample uses supplier item qualifier VN in PO106/07, LIN02/03, and IT106/07. Additional qualifiers, customer item codes, packs, and cartons must be adapted to the partner's guide. Item identifiers remain text, including leading zeros; no unit conversion is performed.
  • Simple USD merchandise totals. No tax, freight, discounts, allowances, or currency conversion is reconciled. Unexpected charges that change TDS cause a mismatch; a pass does not certify every unexamined segment or an entire retailer guide.
  • Observed EDI, not external side effects. The result does not prove warehouse pick/pack, ERP posting, payment, database updates, or partner business acceptance beyond the explicitly checked 855. Add appropriate checks when the evidence exists.

See the checks fail for useful reasons

The maintained conversation cases include passes with and without 855, reordered lines, and equivalent numeric text. They also include the wrong PO, wrong shipment reference, rejected 855, missing or overdue 855, duplicate items, mismatched units, swapped quantities with the same total, changed prices with the same invoice total, incorrect totals, and late shipment. The offline test runs the real binding compiler, X12 fact extraction, and scenario interpreter; transaction metadata is synthetic, and no AS2 receipt or live exchange is claimed.

A green result only covers the checks in this definition. Read the named failing check and its evidence rather than changing the expected result simply to make it pass.

Keep the maps and conversation together in Git

After reviewing the maps, definition, and binding in the browser, use the existing configuration export or repository connection. ModernEDI exports partner/map resource keys and wraps the scenario documents in the normal aggregate format:

modernedi.json
mappings/<mapping-key>/mapping.json
mappings/<mapping-key>/source.x12mapper  (or source.jslt)
scenario-definitions/<definition-key>/definition.json
scenario-bindings/<binding-key>/binding.json

Saved mapping cases live in each mapping's spec.regressionCases. The binding also includes four saved conversation tests: fulfillment with and without an optional 855, a missing 855, and an overdue 855. Configuration verification executes both types before apply without sending EDI. The downloadable files are not a complete workspace replacement bundle: retain your actual partners, connections, and other resources. Let export produce portable binding references instead of committing placeholder numeric IDs.

After an applied change refreshes a binding, use Change history → Conversations in this change to review a fresh run for that revision. Earlier evidence remains historical. The Integration API can automate the same explicit run and transaction-attachment lifecycle without another runner.