To me, useOneAsMany is to BTP Mappings what offside is in soccer: incredibly difficult to understand or explain to a newcomer.
I don't need to use it everyday, so I keep forgetting how it works myself - at the same time, I find the various explanations out there very complicated and hard to follow. So I'll give it a try myself, hoping it will at least help me remember next time I need to use it:
In short: useOneAsMany allows you to reuse a field that occurs only once in a context that occurs multiple times. Think header field on item level.
The confusing part, to me, are the three input variables. Two would make total sense: One that holds the field you want to repeat and one that details how often to repeat. But it has three, and that one tells the system when to inject a context change.
Let's take our example ("use header field on item level") as an example to summarise the parameters:
- Parameter 1 holds the value you want to multiply (i.e. the header field)
- Parameter 2 indicates when the context change occurs (this would be your item node - don't use a field from the item node, use the item node itself!)
- Parameter 3 holds the how often you want to multiply (i.e. an item field that occurs as often as you want your target field to occur, e.g. item number)
If you were just after the How-To, you can stop reading. If you're interested in the background, read on:
BTP builds the target XML in queues. It always goes by the target side, from the top level to the bottom level. Each target field gets its own queue. Say you have a field "item category" and you want to determine it based on a fixed header field "Order Reason". If you simply map them directly (without useOneAsMany), the following happens when BTP tries to build a target queue for item category:
- BTP looks at the source field
- It finds Order Reason
- It sees that Order Reason occurs once in the source
- It maps it for the first item
- No other items get an item category
As the queues are separate, BTP doesn't care how often the fields left and right of "item category" occur. It looks at each field in isolation.
UseOneAsMany multiplies those fields: It pretends that "item category" (parameter 1) occurs as many times as the reference field (i.e. item number) you used. So if you have 10 item IDs, order reason will be mapped 10 times to item category.
And what is the purpose of the second parameter? It tells BTP when to use the next order's header value (context change). Imagine you have 2 orders in your payload. Order 1 has 5 items and order reason A, order 2 has 10 items and order reason B. If parameter 2 didn't exist, we would have halfway solved our problem but introduced a bigger one:
- BTP looks at the source field
- It takes the first Order Reason it finds in the current context (order A)
- It looks at the item ID (the multiplier) and sees that there are 15 items
- It blindly maps order reason 15 times to item category - 5 go to order A, 10 go to order B
- Order 2 receives the item categories of order 1
So the second parameter tells BTP: When you reach the fifth item, start a new queue for field item category for order 2, load the first value for parameter 1 from the current context (order 2), then continue mapping.