Lesson 3 of 6
Mappings and routing
9 min
Listen to this lesson
Most integration defects at Contoso will not be connection problems. They will be a quantity in the wrong unit, a date shifted by a time zone, a partner number that nobody mapped, or an order sent to the wrong receiver. Mapping and routing are where business rules live inside an integration flow, so they are where integration specialists, key users and testers need to agree most precisely.
Four ways to transform a message
| Option | Best for | Watch out for |
|---|---|---|
| Message mapping | Graphical field-to-field mapping between two structures, with standard functions and user-defined functions | Contexts and queues: a wrong context silently drops or repeats values |
| XSLT mapping | XML-to-XML transformations, often reused from existing assets | Readability for the next person; keep it under version control |
| Script (Groovy or JavaScript) | Logic standard steps cannot express, such as complex lookups or payload checks | Untested code paths, performance on large messages, logging payloads by accident |
| Value mapping | Translating codes between systems: units, plants, payment terms, partner IDs | Missing entries; define what happens when a value is not found |
For the Lakeside order, a message mapping maps the ORDERS IDoc segments to Lakeside's order structure. The header segment gives the purchase order number and currency; partner segments give Contoso's buyer and ship-to; item segments give product CMC-RTR-200, 500 pieces and the agreed price. A value mapping artifact translates the IDoc's ISO unit PCE into Lakeside's code EA and plant 1710 into Lakeside's ship-to code for Detroit. SAP's own learning material warns that the mapping context must be set correctly, otherwise values are lost or assigned to the wrong item.
Routing
A Router sends a message down one of several routes based on conditions on headers, properties or payload, written as XPath for XML or as non-XML expressions. Every router needs a deliberate answer to one question: what happens when no condition matches? SAP's guidance for the content-based router offers three options: send to a default receiver, ignore the message, or raise an error. Ignoring is rarely right for business documents.
- Is the purchasing organization 1710 and the supplier Lakeside Components?Yes → route to the Lakeside SFTP receiver · No → next condition
- Is the supplier flagged for AS2 EDI in the partner header?Yes → route to the AS2 receiver for EDI partners · No → default route
- Default route: no condition matchedEnd with an error end event so the message shows as failed and alerts fire, never a silent end
Splitting, multicasting and reuse
A Splitter breaks one message into several, for example a bulk message of 40 orders into 40 single orders, so one bad order does not fail the others. A Multicast sends copies of one message to several branches, for example the same order confirmation to S/4HANA and to an analytics store. A ProcessDirect adapter lets one flow call another in the same tenant, which is how teams share a common logging or error-handling flow instead of copying it into every interface.
- Bulk messageForty orders arrive in one file from a fleet customer.
- SplitterOne message per order, each with its own business key header.
- Mapping per orderValue mapping translates units and partner codes.
- RouterEach order routed by sales area; unmatched orders raise an error.
- ResultThirty-nine orders posted; one failed visibly with its own message ID.
What would you do?
Lakeside adds a new unit code, BX for boxes. A Contoso order uses it, and the value mapping has no entry. The flow passes BX through unchanged and Lakeside's system rejects the order two days later. How should Theo's team change the design?
- Use message mapping, XSLT, scripts and value mapping for what each does best.
- Mapping contexts decide whether item values are kept, repeated or lost; test multi-item messages.
- Every router needs a deliberate default route; raise an error rather than ignore business documents.
- Split bulk messages before processing so one bad record fails alone.
Check your understanding · not graded
Lesson check
1. Which artifact translates codes such as unit PCE to EA between systems?
2. Three items arrive at the partner with the first item's date repeated. What is the likely cause?
3. What should a Router's default route usually do with a business document that matches no condition?
4. Which adapter lets one integration flow call another in the same tenant?