Lesson 2 of 6
Contexts and queues
8 min
Listen to this lesson
Before the mapping runtime builds a single target field, it loads the source message into queues. A queue holds all the values of one source field, in document order. The values are grouped into contexts, and a context change separates one group from the next. The context of a field is the structure it sits in: by default, its parent node. Every time that parent node starts again, the queue gets a context change.
Take Contoso's purchase order 4500000187 to Lakeside Components as an ORDERS05 IDoc. It has one E1EDK01 header segment and three items, each an E1EDP01 segment with an E1EDP19 child that carries the material: rotor CMC-RTR-200, stator CMC-STA-300 and housing CMC-HSG-400. The queue for E1EDP19/IDTNR in its default context holds three contexts with one value each, because each item is a new parent. The queue for E1EDK01/BELNR holds one value in one context.
- Source loadedThe ORDERS05 XML is read into one queue per source field before any target field is built
- Contexts formedValues are grouped by their parent node; a new E1EDP01 means a context change for item fields
- Functions appliedEach function in a mapping expression reads queues and writes a new result queue
- Target builtFor each target node, one occurrence is created per value of its result queue, inside the open parent
- Next target fieldThe runtime moves to the next target field and repeats the cycle
The rule that explains most bugs
The runtime creates target nodes from the result queue mapped to them. A target node gets one occurrence per value in its queue, and target children are filled context by context under their parent. When the two don't line up, values go missing or repeat. SAP's documentation puts the consequence bluntly: values that don't fit into the open contexts are lost.
Two symptoms cover most cases. Only the first group appears: the source context is lower than the target needs, so only the first context is consumed. A header value appears on line 1 only: a field that occurs once is mapped into a node that occurs many times, and the runtime has one value for many contexts. Lesson 3's node functions are the fixes. Before reaching for one, look at the queue.
Changing a field's context
In the Mapping Expression area you can set the context of each source field individually: right-click the source field and pick a higher node, up to the root. A higher context removes the context changes beneath it. SAP's own example uses a product hierarchy (main category, category, product). With the default context, Category, the output lists only the products of the first category. With MainCategory you get the first main category's products. With the root, you get the complete list.
Reading a queue with Display Queue
Cloud Integration gives you Display Queue for any field or function in a mapping expression. Provide a test input file in the Mapping Expression area (you can reuse the file uploaded for simulation) and choose Display Queue. You see the values the node produces and where the context changes fall. It works even when the flow isn't in edit mode, so you can inspect configure-only content too. Make it a habit: queue first, fix second.
| What you see in the queue | What it means | Typical consequence |
|---|---|---|
| A value | One occurrence of the field in this context | Creates one target node or fills one field |
| Context change | The source parent started again | The target moves on to its next parent occurrence |
| Empty context | The parent exists but this field is missing in it | No target node in that context unless you default it |
| SUPPRESS | A value deliberately suppressed, e.g. by ifWithoutElse when the condition is false | The target field and its subnodes aren't generated |
Queue entries and what they do to the target.
Display Queue on the three item materials with the default context shows CMC-RTR-200, context change, CMC-STA-300, context change, CMC-HSG-400. Change the context to IDOC and the same queue shows three values with no context change between them. Neither is wrong; what matters is what the target node expects.
What would you do?
Lakeside's test file from the new flow shows one <code>PO1</code> line, for the rotor, although the ORDERS05 IDoc has three items. Priya asks Theo's developer what to look at first.
- A queue holds all values of one source field; contexts group them by parent node, and context changes separate the groups.
- One target node is created per value in its result queue, filled context by context; values that don't fit are lost.
- Right-click a source field to set a higher context and remove the context changes beneath it.
- Use Display Queue on fields and functions before changing anything.
Check your understanding · not graded
Lesson check
1. What separates the groups of values in a mapping queue?
2. A source field's context is set to the root node. What happens to its queue?
3. In SAP's product hierarchy example, the Product field keeps its default context (Category). What does the output contain?
4. Which queue entry stops a target field and its subnodes from being generated?