Part 1: Split ups are hard? Using the SAP B2B EDI Separator Adapter for a XML Message Split
Split ups are hard? Even in SAP PRO you can do it! Read on, we have a step by step tutorial for you how to do it. Since 2004 when SAP first launched its middleware solution, every subsequent version of the middleware tool has continued to offer capabilities that support business agility in the integration space. SAP Middleware solutions were already known for the capabilities to support varying Application-to-Application (A2A) and where B2B integration was needed, third party solution was typically the option. But since the launch of SAP B2B Adapters, the choice of using SAP PI/PO/PRO as a middleware solution has become inevitable, because of its capabilities to support A2A, B2B as well on premise and cloud integrations.
The options available to achieve today’s scenario of splitting one message into several ones, include:
- ccBPM (only relevant for dual stack deployment)
- SAP Business Process Management tools (BPM)
- SAP PI/PO/PRO tools (e.g with B2B Adapters; which is the option that has been used in this scenario).
Figure: SAP B2B EDI Separator adapter in use for message split.
Figure: SAP Business Process Management Tools and SAP Integration Tools
Achieving complex integration scenarios is now possible, with SAP PI/PO/PRO offering, by using a combination of the various toolsets provided by SAP middleware. This blog aims to share experience and insights as how to achieve the following:
- Sort unorganized data within a large message structure into an easy to understand segmented structure
- Use the B2B EDI Separator Receiver and Sender channels to split this segmented structure into individual messages.
This blog is written in a two part series, where the configuration details are highlighted as well as the integration logic used to achieve the specified business requirements. The first part of this blog will focus on detailing the integration logic in order to “Sort unorganized data within a large message structure into an easy to understand segmented structure”. In the second part, the integration logic and configuration set-up is discussed to achieve a message split: “Splitting a message into multiple messages using the EDI Separator sender and receiver adapter”.
According to the business requirement, this is an A2A scenario that takes advantage of the SAP B2B EDI separator adapter in order to meet all demands.
In this scenario, an enterprise level software solutions for human resource and financial management, is used to manage the HR employee data globally within the organization for new hires. These employee data needs to be synchronized with another internal application periodically. To achieve this, every time this synchronization takes place, records for all employees are combined together in one message. However in the target application – connected by means of a sFTP location – multiple sorted messages are expected to be created per country in form of xml files. To this end, this scenario was set up in the order below:
Step 1: Employee Data with multiple records is sent in one big message from System A to the SAP PRO environment. There, the message is processed by an XSLT mapping to sort the employee data per country (e.g. if there are 10 employees from 4 different countries, all will be sorted into 4 countries), and subsequently an EDI Separator Receiver channel will receive the sorted message for onward processing.
Step 2: The EDI Separator Receiver channel triggers an EDI Separator Sender channel based on configured parameters. Next, it does the splitting of this message into multiple xml messages based on a defined xpath expression (xpath expression to locate the country tag and split into multiple messages based on the number of sorted countries). Subsequently, it will be sent out to the receiving system, System B, which will be done by sFTP.
Figure: Configuration Overview for the use of an EDI Separator Sender and Receiver Channels
As described above, the sender system – system A – parses 1 large message to the SAP PRO environment. This message contains employee data, such as first names, last names, address data, function, join date, and so forth. All these elements are present in the message, and are hierarchically listed per employee. A message can consist of multiple employee records, and are randomly put into the message which means there is no sorting done per employee name, country code, or whatsoever.
In this example, the requirements for the mapping logic differ per country + the receiving party demands for separate files per country. Two very good reasons to realize a message split in SAP Process Orchestration 7.5!
Sorting the message
Part of the message structure from System A is an element that is always occurring per employee record, and is reflecting the country code of the country where the employee is working. Based on this field it is possible to sort the message per country, meaning the Country Code will act as a key. An Intermediate XSD (called XSD EDI Separator in below screenshot) is created, based on the XSD from System A, where another hierarchy level has been added and which is called ‘Country’.
Under the newly created Country node, the employees that work in a particular country are listed. A new Country node will be created as soon as the input message contains a worker from a Country which so far was not present in the target message. Please keep in mind that the message will not be split yet in this mapping; the mapping only facilitates the splitting. This split part will be done later by the EDI Separator Component itself. Below, this situation is displayed in a graphical manner.
The reason for adding an additional hierarchy level is to be able to select a unique node from the intermediate message in the EDI Separator component. By selecting this node in the configuration of the EDI Separator, the SAP PRO system knows where to split the message into multiple ones. The new messages will all start with Country as first node. More on this can be found in the second part of this blog.
Figure: Unsorted Input Message and Sorted Output Message
Note: The Intermediate XSD has another additional element, which is called ‘EDI_Separator_Identifier’. Based on this field, which is filled with a constant value, it is much easier to create a filter in the EDI Separator Sender Communication Channel. More on these configuration steps can be found in the second part of this blog.
Right now the focus will be on how to create a mapping that sorts the single large message in such a way that the EDI Separator component is able to split the message per Country Code. Again, this splitting will later on be done based on the Country node.
In order to create the intermediate message structure, a SAP PRO consultant has three options: A graphical mapping, a XSLT mapping and a JAVA mapping.
A graphical mapping should be fairly easy with the standard sort and ‘sortByKey’ statements that are available. Next, there is the possibility to create User Defined Functions where needed. However, when this option is chosen one comes across (at least) two difficulties:
- All individual elements should be sorted by the key you are using – in this case Country Code. In case of a XSD with numerous elements, this copy pasting of logic becomes quite a chore.
- In case segments can occur just once, multiple times, or not at all, it is likely that one comes across context issues. For instance, how to make sure the right amount of context changes are still present under the correct employee?
A suitable option for this scenario is creating a XSLT mapping where a ‘countryKey’ is defined, based on the element of the source structure that is filled with the Country Code data. As a first step this element is selected from the input message, where after a unique ID is assigned to each Country Code.
During the second step a new message structure needs to be defined; the one that is called Intermediate Message in this blog. A variable has been created first, variable ‘currentCountry’, and will be used to generate the new message node ‘Country’. The for-each statement creates a key based on all the Country IDs. This key is then passed to variable currentCountry.
Finally, all employee data records and all hierarchical segments belonging to the specific Country Code will be copied 1:1 under node Country. The same happens when a new Country Code appears from the source message; all employee records that have that exact same Country Code will be copied under the newly created Country node.
Figure: Overview of XSLT Mapping logic for message sorting (Credit to: Frans van Gelderen for this logic)
Conclusion and Part 2
In this blog, an overview of the integration scenario, the integration logic and the SAP PRO tools used in achieving this scenario have been presented. The complete scenario set up requires building two Integrated Configurations (ICOs), the set-up of the first Integrated Configuration and the XSLT mapping logic required to achieve “sorting of the message” has been discussed. Subsequently, a second part of this blog would be published. This will explain the set-up of the second Integrated Configuration (ICO) as well the settings needed for the EDI Separator Receiver and Sender communication channels respectively. Watch out for the second part of this blog!