B2B Mapping Techniques Using the Graphical Mapping Tool

[Former Member]

One of the important tasks for B2B development is providing a mapping solution between different interfaces, from sender to receiver. Sometimes the interfaces vary dramatically in terms of structures, cardinalities, etc. As we all know , the SAP Exchange Infrastructure (XI) offers a great and powerful tool, the Graphical Mapping Tool, to solve the mapping related issues. It might be actually the best option for developers who work on their B2B projects on XI. This blog will introduce some mapping techniques while developing mapping objects using the XI Graphical Mapping Tool.  

A Brief Overiew on the Tool

Let us have a quick overview on the tool itself before I get into much detailed examples of the mapping strategies. With XI Graphical Mapping Tool we can create message mapping objects in XI. And there is always a source interface and a target interface in a message mapping object. Thus, the mapping is always between the source interface and the target interface. A JAR file will be created upon the activation of the corresponding message mapping object in XI. Therefore, the JAR files is being used during runtime.   The graphical presentation of the tool not only provides a fancy-looking and user-friendly interface to the developers, but also carries information on interfaces, especially for the target interface. There are basically three types of icons being used: with four different colors representing: As I have mentioned above, the different types and colors of the icons associated with target mapping fields/segments carry important information, such as the cardinalities, of the target interface. The information is actually coming from the DTD or XML schema of the target interface. Therefore, we need consider those icons while we design our mapping logic for the corresponding mapping fields or segments.  

Mapping of Structure Fields

We often received some questions regarding the mappings of the structure fields (segments). The questions can always be simplfied to "Do we need put a mapping for the particular structure field?" Well, the answer is "It depends." Because, the generation of structure fields depends on 1). How often those structure fields occur in the target structure (i.e., their occurence) and 2). If there is a target field mapping has been defined for the structure fields. (i.e., their mapping).   There is a generic rule from the Graphical Mapping Tool governs if a mapping is required for the structure fields based on their occurences: As a general rule of thumb, we do not have to map a target structure field ONLY if minimum and maximum occurences of the target structure field are the same. This means, you will need a mapping to generate the target structure fields whose minimum and maximum occurences do not match unless you do NOT want to generate the target structure as well as the fields and sub-structures sit underneath. If you do not want to generate a target structure, please bear in mind this is ONLY allowed if the target structure carries the minimum occurence of zero, or the mapping would fail with Java exceptions thrown. 

Subtree Duplication

Some structures are allowed to occure multiple times in a document if their maximum occurences are greater than 1, while by default elements are only displayed once in the structure overview of the Graphical Mapping Tool. Sometimes we need apply different mapping logic to different target structure fields to carry different information. Hence, we need duplicate the subtree of the target structure field in our mappings. Let us take a quick look at the following example: This is a mapping from CIDX (a chemical industry standard) interface to IDoc (SAP proprietary) interface. The two interfaces use two different ways to store partner information. On the left-hand side, the source CIDX interface has different partner roles, such as, Bill To, Ship To, Supplier, Sold To, etc. While on the right-hand side the target IDoc interface utilize E1EDKA1 segment with its PARVW field to distinguish among different partners. But, there is only one E1EDKA1 segment displayed on the target structure overview. I can apply mapping from "Bill To" Partner to the E1EDKA1 segment, but I need more E1EDKA1 segments to apply the mappings from "Ship To", "Supplier" adn so on... How am I gonna do this??? Well, the solution is just simple...

1. Apply the mappings for the target subtree, i.e., the mappings from "Bill To" Partner to E1EDKA1 subtree in this case.
2. Highlight the root of target subtree to be duplicated, i.e., the E1EDKA1 structure field in this example.
3. Right-click on the subtree highlighted, and select "Duplicate Subtree" from the drop-down menu.
4. Apply the mappings to the subtree just duplicated.

Note: You DO need apply mapping to the root of the subtree just duplicated, in order to have the whole duplicated subtree as well as all the mappings applied to its sub-structures saved properly. You will lose the duplicated subtree and its mappings after you saving the message mapping object without assigning a mapping to the root element of the subtree itself. 

Use of createIf Function

Okay, too much on the Subtree Duplication topic. And now, let's swap the two interfaces, and have a look at the opposite situation. We now have IDoc interface on the source side with CIDX on the target side. Again, we are still doing the mapping for the partner fields. The source IDoc interface adopts E1EDKA1 segment with its PARVW field to differentiate among different partners, while the target CIDX interface has different partner roles defined, such as, Bill To, Ship To, Supplier, Sold To, etc. Which means, there are multiple E1EDKA1 segments with different PARVW values to represent different partners in the source input XML document, while the E1EDKA1 segment only exist once in the source structure overview. Moreover, all of these E1EDKA1 segments, and their subtree fields as well, need to be mapped to the corresponding partner roles defined by CIDX on the target side.  The createIf function can help us on this sort of scenarios. In general, the createIf function can be applied to a mapping logic generating the target segment node based on a condition. Let's take a look at the following example using createIf function. The E1EDKA1 segment, whose PARVW is 'AG', carries the partner information of the buyer's role. Therefore, this whole E1EDKA1 segment on the source side needs to be mapped to the Buyer/PartnerInformation segment of the Buyer's role on the target side.  The solution to this problem is shown as above.

1. Use equalS function to check the 'PARVW' field from E1EDKA1 segment if it carries the text value 'AG'.
2. Use createIf function to link the output of equalS function and the root element of the target subtree, i.e., Buyer/PartnerInformation.
3. Direct map the fields sit underneath of E1EDKA1 node to the corresponding fields from the Buyer/PartnerInformation segment on the target side.

Note: You are NOT done yet! There is one more thing you need do. Please go back to the target segment node Buyer/PartnerInformation again. You should have the same mapping structure in the data-flow editor as shown above. To ensure proper generation of the target segment fields, you need set the context of the field PARVW to two levels upper instead of one level up by default. To set context of field PARVW to two levels upper, i.e., IDOC level in this case,

1. Select node PARVW in the data-flow editor.
2. Right-click on the mouse.
3. Select Context -> IDOC.

After you have changed the context to a different level as default, you can see the font on the PARVW node has changed to italic. Now, your mapping should be to generate the target Buyer/PartnerInformation segment based on the condition if the PARVW field from E1EDKA1 is 'AG'. The createIf function will suppress all the other E1EDKA1 segments whose PARVW are not 'AG'. This will ensure the proper mapping for all the fields sit underneath.  

Synchronizing Parent/Child Pair

There is a rule set by the Graphical Mapping Tool requiring each pair of target parent and child queues synchronized. To be more specific, for each value, real or"suppressed", in a queue for parent-node (e.g., structure field), there must be a context in a queue for child-node, while if there is an empty context of parent-node, i.e., no value in it, there should NOT be a context fo child-node. Adhere to this rule will always keep the parent and child queues synchronized to each.   Note: This rule applies to each pair of parent and child nodes.  To better understand the rule, let's take a look at the following example : Here, on the target side, we have an optional structure, telephoneNumber (0...1), and its mandatory child field CommunicationsNumber (1...1). The whole segment is optional; however, if there is a parent structure, the child field is mandatory. Therefore, if there exists a corresponding source field in the IDoc side, which needs to be mapped to the child field, then the whole segment, parent and the child, must be created in the output document. And if there is no such field in the source side, then the whole segment should not be generated at all. The TELEPHONE1 field of IDoc E1ADRM1 segment is the only source field to both of the parent and child target fields. Moreover, we also need generate the grandparent node -- ContactInformation (0...1) based on the condition, which is PARTNER_Q from E1ADRM1 segment should equal to 'AG'. To have our mapping work, we need make sure that not only the output queues of the parent and child nodes synchronized, but also the queues of the grandparent and the parent should be synchronized as well.  We can use the following mapping technique to achieve this:

1. Apply a mapping to the grandparent node, ContactInformation, based on the condition if PARTNER_Q ='AG'. This mapping logic is similar to the example we discussed in "Use of createIf Function" Section.
2. Direct map TELEPHONE1 field to the parent node telephoneNumber.

3. We can map the source field TELEPHONE1 to the child filed, CommunicationsNumber, with the help of removeContexts Function and SplitByValue Function as shown below. The removeContexts Function will remove all the contexts in the TELEPHONE1 queue.

4. Double click on SplitByValue node in the data-flow editor, select "Each value" from the drop-down menu. Here, the SplitByValue function will insert the context changes after each value to ensure the child queue is synchronized with its parent queue.

Replication of Input Queues

How to replicate an input queue is a common requirement for the developers when designing their mapping solutions. This is simply because there are not enough values in the input queues which need to be mapped to the target side, and most of the time the mapping would fail if this has not been taken care of. claus.wallacher/blog has posted an excellent blog in SDN Replication of Nodes Using the Graphical Mapping Tool discussing the problems and solutions of replicating input queues in details.