Skip to Content
Author's profile photo Eng Swee Yeoh

Stop using External Definition for 1-N IDoc multi-mapping ©


Let’s take a stroll down memory lane

In the early days of XI 3.0 and PI 7.0, it was not uncommon to come up with workarounds to meet the various integration challenges. One common requirement is to post multiple target IDoc messages from a single source message. This required a 1-N IDoc multi-mapping (also called mapping-based message split). Back then, there was a restriction for mapping-based message split as described in the below snippet from the blog Multi-Mapping without BPM – Yes, it’s possible!

Messages that result from the split in a mapping-based message split are sent using one AE. So only adapters running on the AE are supported. In particular, this means that target IDOC message splits are not supported since the IDOC adapter is not part of the AE.

As the IDoc adapter was ABAP-based in those dual-stack days, this meant that such splitting was not possible for target IDoc interfaces in the “truest sense of the word”. However all is not lost, as the workaround for such a requirement is to change the occurrence of standard IDoc by exporting the standard IDoc schema, changing the root node’s occurrence to “unbounded” and reimporting it as an External Definition.

Fast forward a few years and in PI 7.11 the restriction mentioned above has been removed (I’m not sure of the behavior in a PI 7.1 system as I didn’t work on one). Although the IDoc adapter was still ABAP-based (IDoc_AAE was only introduced in 7.3x), the behavior of the adapter has changed.

In various client systems I have worked on, as well as on SCN’s forum, it is evident that the workaround using external definitions are still used for IDoc interfaces. As the restriction has been removed, it is no longer necessary to use an external definition for IDoc when performing mapping-based message split. As this is a lesser known fact in the community, therefore this post aims to highlight this and to bring awareness of the redundancy of the above mentioned workaround.


Below is an example scenario of how 1-N IDoc multi-mapping can be achieved without using External Definition. This example is based on a single stack system which uses IDoc_AAE but conceptually it applies to the ABAP-based IDoc adapter on any dual stack system since PI 7.11.

Instead of using an externally modified IDoc definition, we can just use the imported IDoc definition as the Target Message/Operation in Message/Operation Mapping. For the Occurrence column, change it from 1 to 0..unbounded.


When end-to-end testing is performed, we can see that the output of the multi-mapping produces the <Messages> and <MessageN> nodes wrapping the IDoc structure. This verifies that a mapping-based message split has occurred.


The audit log shows that the mapping has split the message into multiple child messages.


Upon viewing the child messages generated from the split, it shows that the <Message> and <MessageN> nodes are automatically removed from the child payload.


And finally, the child messages are delivered to the IDoc receiver channel and processed successfully.



As detailed in this article, the workaround using modified External Definition is no longer required to achieve 1-N IDoc multi-mapping. Instead this can be easily achieved by changing the Occurrence in the Message/Operation Mapping. Hopefully this will help raise awareness in the community, thereby removing redundant and unnecessary workarounds during the development of 1-N IDoc interfaces.

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Jegatheeswaran Pitchaimuthu
      Jegatheeswaran Pitchaimuthu

      Hi Eng Swee

      Thank you for the blog.

      We followed this design in our IDoc ibound interfaces. (File to IDoc).

      Business has asked some attributes from the payload in the alert email messages.

      I have configured the same (UDMS attributes - NWA) by referring the Outbound Service interface which is for file.

      When the message splits, UDS attributes appeared in the Outbound message, inbound messages did not have, i.e split idoc messages

      When the split message is failed, the alert e-mail messages did not have UDS attributes.

      Then I changed the UDS configuration by referring fields from the inbound interface i.e IDoc.

      After change, UDS attributes are displayed in each individual split idoc messages, but the alert is triggered only for first message with UDS.

      Remaining inbound messages though failed with UDS attributes in MM the alert is not triggered. i.e When I check the alert job log, it says no alerts are suppressed and no alerts are aggregated. (I tried this test by stopping IDOC_AAE receiver channel)

      I could not understand why.

      One thing we observed that this problem comes only for split messages.

      Could you please clarify how to overcome this with this approach?

      (When I switch to older format (IDoc XSD), an alert e-mail message comes correctly with UDS attributes for all records which is in the message since it is only 1 message)


      Thank you.

      Author's profile photo Eng Swee Yeoh
      Eng Swee Yeoh
      Blog Post Author

      Hi Jegatheeswaran

      Thank you for your comment. However, it would be more appropriate to raise your issue as a thread in the forum instead. Your issue require more details for a thorough analysis and it is not suitable to be done over the comments section here. Additionally, other members would be able to contribute to the analysis as well.

      When you raise your thread, please include as much specifics and examples for your case (i.e. sample source and target payloads, screenshot of errors/alerts, UDS configuration). Please also provide the PI version and SP level.


      Eng Swee

      Author's profile photo Daniel Graversen
      Daniel Graversen


      Great blog.

      It does make sense some times to use the split mecanism that you provide here and in most cases it will be okay.

      It gives some more visibility to the number of messages that you have in the payload.

      though this can also make it less visible to what else is being processed.

      I belive that the bundled idoc will make less strain on the PO AEX system because there is not all the extra processing about creating new spit messages.

      Author's profile photo Eng Swee Yeoh
      Eng Swee Yeoh
      Blog Post Author

      Hi Daniel

      Thanks for your feedback.

      Regarding the strain on the system, is this a hypothetical assumption or based on real-life experience that you have encountered? I have used this split mechanism over many interfaces on many systems and have never experienced any negative performance impact caused by it.

      Do you have any statistics of such performance comparison to back this up? This would help others to take this factor into consideration when designing such interfaces.


      Eng Swee

      Author's profile photo Nidhi Srivastava
      Nidhi Srivastava

      Hi Eng,

      We are having a requirement where we need to have multiple idocs at the source.810 INVOIC ANSI X12 is there, where we need to pack the idocs and send those as a single message.

      Do we just need to change the occurrence and it will work or we need to do necessary settings in ECC systems as well.

      Please advice what all needs to be checked.



      Author's profile photo Eng Swee Yeoh
      Eng Swee Yeoh
      Blog Post Author

      Hi Nidhi

      For packaging of multiple IDocs on the sender side, you don't need to change the occurrence. Instead you need to set packaging on the IDoc sender channel and adjust the partner profile to Collect. Refer following blogs:-

      IDoc Packaging - SAP PI 7.1 EHP1 (and above)

      IDoc Packaging with PI 7.11 (and above)

      If you still face any issues with this, please raise it as a thread in the forum instead.


      Eng Swee

      Author's profile photo Nidhi Srivastava
      Nidhi Srivastava

      Thanks Eng, will do that.



      Author's profile photo JuanK Gutiérrez
      JuanK Gutiérrez

      Hello Eng Swee.

      I am trying to achieve in CPI what you show us in this excelent post, but I haven't been able to do it.

      I do see the ocurrence selectors in the 'Source and Target Messages' screen.


      Ocurrence selector in Source and Target Messages screen

      When you select '0..*' in either side, the definition changes for both sides, the nodes 'Messages' and 'Message1' are now wrapping the original definition and original definition root node in the side you change ocurrence has now multiplicity '0..*'.


      Original definition changes in both sides, they now have Messages and Message1 nodes wrapping them

      I tried several options to map the wrapping nodes in the target side (mandatory since their multiplicity is '1..1'): with respective nodes in source side (non-existant in reality), with source root node and some of underlying nodes; but I'm always getting the following error: Cannot produce target element /ns1:Messages. Queue has not enough values in context. Target xsd requires a value for this element, but target field mapping does not produce one. Probably the xml-instance is not valid to the source xsd, or the target field mapping does not fulfill the requirement of the target xsd.

      What I haven't tried is to change the source side definition to force to have the 'Messages' and 'Message1' nodes wrapping the whole original message.

      Do you happen to know how to map these wrapping nodes on the target side in order to achive mapping based message split in CPI? I didn't find any releated posts or questions in the community using 'mapping based message split' and cpi as criteria, I also tried other criteria but didn't find anything useful.

      Thanks for any help you can offer.