qbit-edi/docs/MAPS.md

EDI maps

A map comprises an edi_map row and ordered edi_map_rule rows. EDI paths resolve through the guide's loop tree; target paths support one association level. condition, defaultValue and required apply within each loop occurrence. Missing optional values preserve child alignment.

transformArgs is a JSON object with string values. Omitted transforms copy the first value.

An inbound ediPath may join several element paths with + (outside any [...] predicate); their values are concatenated in order. This is how a date and a time held in separate elements reach DATETIME: G62[G6201=10]/G6202+G62[G6201=10]/G6204. Inside a [*] loop path only the part after the anchor is split (S5[*]/G6202+G6204). A condition such as present(G62[G6201=10]/G6202) skips the rule when the elements are absent; a transform with no input otherwise fails the rule.

Transform	Arguments / result
DATE	CCYYMMDD or YYMMDD; fixed 1950–2049 century window; QQQ date
TIME	HHMM, HHMMSS, fractional seconds; normalized string
DATETIME	Date and time values, or time argument; timezone defaults UTC
DATEPART / TIMEPART	Outbound halves of a DATETIME: a QQQ timestamp (an instant, an offset timestamp, or a zone-less one read as UTC) rendered as CCYYMMDD or HHMMSS in the timezone argument (default UTC)
DECIMAL	scale implied decimal places, default 0
QUALIFIER	Sibling predicate in ediPath, e.g. N1[N101=ST]/N104
CODE	Map-local translation object, e.g. {"EA":"each","CA":"case"}
UNIT	factor, divisor, scale (defaults 1, 1, 6), HALF_UP
CONSTANT	value; needs no EDI input
CONCAT	separator, default empty; joins selected values
SPLIT	Literal separator (comma), zero-based index (0)
SUBSTRING	Zero-based start inclusive, end exclusive
TRIM / UPPER	Whitespace trim / locale-independent uppercase
LOOKUP	table, key, result (default id); exactly one permitted row
SEQUENCE	Outbound loop occurrence, starting at start (default 1)
HL	Outbound HL01 counter, HL02 nearest parent, HL03 code, HL04 child indicator

Supply the partner timezone explicitly for DATETIME. UNIT uses configured conversion factors/pack sizes; host-dependent field lookups and code-list translation can register named transforms through EdiRuntime.current().transforms().register(name, transform). Transforms execute as the service session. LOOKUP explicitly enforces permissions.

Samples reference encrypted PayloadStore objects. Preview JSON contains values and recursive associations; expectedResultJson uses the same shape. Comparisons show structured before/after JSON as Result lines. Preview never invokes target application. See the synthetic 850 resources under src/main/resources/edi/maps and GUIDE-FORMAT.md.

Outbound maps

OUTBOUND rules are evaluated in sequence order. EDI path prefixes create nested loop scopes; the directly mapped QQQ association drives each occurrence. Nested QQQ paths such as cartons.items.sku are supported and fetched recursively by the worker. Constants within a loop can carry an association field as qqqPath to identify their scope. See the 856 samples for Shipment/Order/Pack/Item loops and parent numbering.

DATE/TIME format QQQ values as X12 dates/times; DECIMAL multiplies by the implied scale. Other registered transforms operate on the source value. Conditions use the existing EDI rule language over segments already emitted. A missing required mapping input fails mapping; structurally invalid mapped output opens VALIDATION and is never sent. ST/SE or UNH/UNT are generated by the mapper; the worker allocates controls. Component-target paths use -, for example LIN03-1 and LIN03-2, and retain components separately so the EDIFACT writer can escape data.

Warehouse and logistics samples

Phase d adds baseline guides and sample maps for four documents; test sources define the synthetic sample_wms_*, sample_shipment_status and sample_load* tables. Maps with a second direction use an -in or -out file suffix.

File	Direction	Target	Business key
940-*-sample.json	INBOUND	sample_wms_order + lines	W0502 (secondary W0503)
945-*-sample.json / 945-in-*	OUTBOUND / INBOUND	sample_wms_shipment + lines	W0602
214-*-sample.json	INBOUND	sample_shipment_status (flat, first LX event)	B1002 (secondary B1001)
204-*-sample.json / 204-out-*	INBOUND / OUTBOUND	sample_load + stops	B204

Order dates and appointments arrive as DATETIME from a qualified G62 (G62[G6201=10]/...) or from the stop's G62 and leave as DATEPART plus TIMEPART. The 204 stop address is read from the nested loop (S5[*]/S5N1/N102; the guide gives the stop-level N1 loop its own id, S5N1, so it does not collide with the header N1 loop) and the stop sequence is mapped from S501. A 214 can carry several LX events; the sample map records the first (LX[1]/...) and a host that wants all of them maps an association instead. Optional outbound qualifiers such as MAN01 and L1102 are constants, so the sample source rows must carry the value they qualify (the carton SSCC, the bill of lading).

EDIFACT retail samples

Each of D96A and D01B includes ORDERS-<version>-sample.json inbound to sample_order and lines, and outbound ORDRSP from sample_order, DESADV from sample_shipment with cartons.items, and INVOIC from sample_invoice with lines. Test sources define these synthetic tables. ORDERS carries its business key in BGM02, date in qualified DTM01 component 2, buyer in qualified NAD02 component 1, and items in SG25. BGM's document codes are 220, 231, 351 and 380 respectively. These subsets intentionally carry only the fields exercised by the samples.

Composite paths address values, not delimiter-joined strings. An identifier containing +, : or ' remains a single value; the writer supplies release escapes. The outbound agreement owns UNA settings. Separate map resources per directory keep future version-specific changes isolated.