Message Mappings in SAP XI

Use

A message mapping refers to a mapping of messages and is supported by a graphical mapping editor. The editor enables you to design a structure mapping between any two XML structures and connect to a value mapping.

The mapping tool generates Java source code from the graphical mapping description, which is then compiled and packed in a JAR file that the Integration Engine executes at runtime.

Features

The mapping editor can load the following schemas into the structure overview:

· A schema from the Integration Repository: (Fault) message types, IDocs, the request, response, or fault part of RFCs, and message structures from external definitions. The latter are message structures from WSDL, XSD, or DTD documents.

· XML schema definitions (XSD) or XML files from a local file

In the case of XSD files (the repository schemas also use this format), the mapping editor generates an XML representation for both the source structure and the target structure. If the XSD file contains more than one global element, use a dialog box to select a global element as the root element.

If you want to load several XSD files that reference each other using the import and include XSD statements, you must first pack the files into a Zip file. If the file contains multiple global elements, you must select one global element as the root element in this case as well.

Main Function Area of the Mapping Editor

Once you have created a message mapping, the system navigates to the mapping editor Design tab page. The figure below illustrates the screen areas of the mapping editor (the tab page was detached from the Integration Builder beforehand):

You have the following options when defining a message mapping:

· The functions in the Object Toolbar relate to the entire mapping. For example, you can save your mapping or automatically assign fields with the same name to each other.

· When you create a new message mapping the Structure Overview in the mapping editor is initially empty. Here you must specify a repository schema for both the source structure and the target structure or import an XML or XSD file. The mapping editor imports the data and displays an XML representation for the mapping in the Structure Overview: In this screen area, the source structure is on the left and the target structure is on the right. Source structure fields then have to be mapped to target structure fields. You have various options for displaying the source and target structure (Tree View, Tree and Table View, display as a text document, or display in the browser) that you can select from.

· The structure overview is closely linked to the Data-Flow Editor, which you use to describe the mapping of one or more source fields to one target field. This type of mapping is also referred to as a Target-Field Mapping. If a field in the target structure has already been mapped, you can navigate to the respective mapping by double-clicking the corresponding target field in the structure overview.

Therefore, a message mapping comprises various target-field mappings. Once you have defined a mapping for each mandatory target field your message mapping is complete. To test your message mapping, navigate to the Test tab page (see: Test Environment).

Functions of the Object Toolbar

Function	Use
Select Messages	Loads schemas for source and target messages into the structure overview.
Map Selected Fields and Substructures if Names Are Identical	Before you execute this function, first select one node in both the source and target structures that belong to each other. You can then automatically assign subnodes that have identical names (names are case-sensitive here). This function is particularly useful for simple mappings, for example from RFC XML to proxy XML.
Clear Mapping	Deletes all target field mappings.
Data-Flow Editor	Use this button to switch between the data-flow editor, text preview, and mapping templates used, in the lower area of the data-flow editor: · In the data-flow editor, you edit target-field mappings. · You use the text preview to display all target-field mappings and the functions that they use as text. Lines in red indicate missing target-field mappings. The quick info for a green target field displays the corresponding mapping. · A message mapping can reuse mapping templates (for data type mappings). Using Mapping Templates Used you can display all the mapping templates used so far in the lower area of the mapping editor. Note that the target-field mappings of the mapping templates used may differ from those in the current message mapping.
Text Preview
Mapping Templates Used
Dependencies (Show, Show All, Hide All)	Use this function to graphically display which source fields are assigned to which target fields in the structure overview (for a selected node pair, or for all). The colors have the following meanings: · Red: The source field is directly assigned to the target field. · Green: A subnode of the source field is assigned to the target field. · Blue: The source field is assigned to a subnode of the target field. · Black: A subnode of the source field is assigned to a subnode of the target field.
Show Suitable Templates	Use this function to load a saved mapping template for an element pair as a copy.
Create Template Based on Mapping	Use this function to create a mapping template for an element pair that references a data type or a message structure. You must select the respective elements.
Dependencies (Show, Show All, Hide All)	Use this function to graphically display which source fields are assigned to which target fields in the structure overview (for a selected node pair, or for all). The colors have the following meanings: · Red: The source field is directly assigned to the target field. · Green: A subnode of the source field is assigned to the target field. · Blue: The source field is assigned to a subnode of the target field. · Black: A subnode of the source field is assigned to a subnode of the target field.
Edit Java Sections	Use this function to specify global variables and additional Java sections for all Java functions. First the mapping runtime includes the Java packages specified under Imports. You can enter the same packages entered for a user-defined function. Then the mapping runtime declares the variables entered as global variables and executes the sections in the following order: ... 1. Initialization section 2. Message mapping 3. Cleanup section

Functions in the Message Mapping Object Menu

Function	Use
Refresh	If you loaded a repository schema into the mapping editor that has since been changed in the Integration Repository, the changes are not visible in the mapping editor. To apply changes of this type to the source and target structures, choose Refresh.
Delete	This function deletes the message mapping object.

Additional Functions

Within the structure overview and in the data-flow editor you can call functions in the context menu. For all fields (in the data-flow editor and in the structure overview on both the Design and Test tab pages) you can copy the path for a field to the clipboard by choosing the context menu option Copy Path.

Activities

To define a mapping between two XML structures, proceed as follows:

...

1. Create a message mapping on the design maintenance screen of the Integration Builder (see: Creating a New Object).

2. Load a source and target structure in the mapping editor by either using the search help, or by using drag and drop to drag a name from the navigation tree and drop it on the corresponding hand.

For messages from external definitions, note that the mapping editor does not support the entire language range of XSD. For more information, see SAP Service Marketplace at service.sap.com/xi ® Media Library ® Documentation: SAP XI 3.0 (SP11) – Supported XML Schema and WSDL (EN).

3. Using the structure overview and the data-flow editor, assign one or more source fields to a target field. This type of mapping is also called a Target-Field Mapping. It is also possible to assign one source field to multiple target fields (see: Assigning a Field).

4. If necessary, enhance the target field mapping in the data-flow editor. To do so, connect the source fields to the target field by using the standard functions of the mapping editor. You can also create user-defined functions in Java in the mapping tool and then use them in the data-flow editor (see also: Data-Flow Editor).

5. Carry out the last two steps for all mandatory target fields at least.

Result

The mapping is complete and ready for testing when all the fields in the target structure have either green or white icons. A yellow icon indicates that a target-field mapping is incomplete, while a red icon indicates that target fields are unassigned.