Designing Mappings in SAP XI

Purpose

In SAP Exchange Infrastructure, interface descriptions of function calls (interfaces) are saved in XML format. The parameters of these interfaces determine the contents of the messages that are exchanged between systems (see also: Interface-Based Message Processing).

A mapping refers to the mapping of interfaces or messages to other interfaces or messages. You may need to use mappings of this type in a cross-system business process for a variety of reasons:

· A business partner expects other technical field names or another structure for transferring data.

· For technical reasons. For example, an RFC receiver adapter connected to SAP Exchange Infrastructure expects to receive messages from the Integration Engine in the format that it can understand, namely RFC XML. It then creates an RFC call in a system assigned to it. If the Integration Engine receives a message from a client proxy (BC-XI), the corresponding message must be mapped to RFC XML using a mapping so that the receiver adapter can process it.

You can define one or more mappings for an interface pair at design time, and save them in the Integration Repository. At configuration time, you can then select the mapping that corresponds to a specified business scenario. The Integration Engine transforms the message at runtime, in accordance with the saved mappings. Ideally, no mapping is required. In other words, the sender and receiver interface parameters are identical.

Implementation Considerations

Mapping is an essential part of SAP Exchange Infrastructure. At design time mappings can be saved in the Integration Repository and then selected for a business process at configuration time (see: Defining Interface Determinations). The Integration Engine executes the mappings saved in the Integration Directory at runtime, following receiver identification. If no mapping is required for a connection then the Integration Engine skips the mapping step.

Features

SAP Exchange Infrastructure differentiates between the following at runtime:

· Mapping Programs: Used to implement the mapping.

· Interface Mappings: Used to register mapping programs for an interface pair. You can also enter multiple mapping programs that are executed in succession.

Mapping Programs

The Integration Builder supports the following:

· The development of message mappings using a graphical editor integrated in the Integration Builder. Java classes are generated for use at runtime from a graphical description. You also have the option of enhancing the standard functions with user-defined functions.

· The import of XSLT or Java mapping as an archive. If, for example, XSLT mappings already exist or are to be developed using third-party tools, you can use the import function to import such mapping programs into SAP Exchange Infrastructure.

These mapping programs are executed on the J2EE Engine of SAP Web AS. SAP does not ship any mapping programs that run on the ABAP Engine. However, customers can develop such mapping programs by using the ABAP Workbench, see Mapping Development with the ABAP Workbench.

Imported archives

Type	Use
XSLT (eXtensible Stylesheet Language Transformations)	You use XSLT to convert an XML document to another document. This is achieved by using XSLT commands to search for tags in the source document and replacing them with other tags or values in the target document. It is also possible to switch to a Java program from XSLT.
Java Program	The message is transferred to a Java program as an inbound stream and can be imported using any parser (for example, SAX or DOM). The modified message is then transferred to an outbound stream. A Java program can also be a help program that in turn is used in another Java program or self-defined functions of a message mapping.

Overview in SAP XI Designing Mappings

You can define mappings for an interface pair (source and target interface) by using message interfaces and message types in the Integration Repository.

You can also define the corresponding mappings when the source or target interface is an IDoc, an RFC, or another interface connected by an adapter.

As illustrated in the graphic, in the standard case a request contains the data that is defined using the output message type of the outbound message interface. At runtime, a request passes from the outbound to the inbound interface. In the same way, the response contains the data that is defined using the output message type of the inbound message interface. It passes in the opposite direction to the request. If errors are thrown on the inbound side, these can be reported to the sender by using fault messages and then handled there. A fault message, like a response, passes from the inbound interface to the outbound interface. You can define mappings for request messages, response messages, and fault messages. Exchange Infrastructure supports the following mapping programs for this purpose:

● Message mappings that you define using a graphical editor in the Integration Builder. This is used to create a Java source code for the runtime.

● XSLT and Java mappings that you can import into the Integration Repository as an archive.

● XSLT and ABAP mappings that customers can implement using the ABAP Workbench (see Mapping Development with the ABAP Workbench).

Essentially it is possible to create or import multiple mapping programs in the Integration Repository for the same output or input message type pair (or the corresponding part of an imported or external interface).

Comparing Mapping Program Types

SAP recommends that you use message mappings. However, in exceptional cases it may be advisable to use different mapping programs, for example, because you can apply XSLT or Java mapping programs from a previous integration project.

Note the following regarding the speed at which the mapping program types are executed:

● Handwritten Java programs by experienced Java developers are usually quicker than generated Java source code from message mappings.

● Message mappings can cope with significantly larger messages than XSLT. Whether an XSLT program or a message mapping is quicker depends on the complexity of the mapping. Tests have shown that even message mappings for larger messages are quicker than the equivalent XSLT mapping programs.

● Experience has also shown that Java-based mapping programs are quicker than ABAP-based mapping programs.

Interface Mappings

When defining mapping programs for request, response, or fault messages, the definition is first separated from the interfaces that reference the corresponding message types. Furthermore, you can reuse a message type for multiple interfaces. This means that the simple definition of a mapping program is not sufficient to establish a connection (that is based on the assignment of outbound and inbound interfaces).

This role is undertaken by the interface mapping:

● An interface mapping specifies the corresponding mapping programs for request, response, or fault messages for a selected interface pair. You use an interface mapping to register mappings for an interface pair.

● You can also specify multiple mapping programs to be executed one after the other in the case of requests and responses for an interface mapping.

You can also define multiple interface mappings for the same interface pair, to provide multiple variants in the Integration Repository. At configuration time, the customer can select the appropriate mapping in an interface determination and save it in the Integration Directory.

Structure and Value Mapping

There are two types of mappings, regardless of the mapping technology that you use:

● Structure mappings where the structure of an XML document is mapped to the structure of another XML document.

● Value mappings where the values of an XML document are mapped to the values of another XML document.

Example

In the example below, data about a flight booking is exchanged using XML documents. The XML schema of the source document provides more hierarchy nodes than the XML schema of the target document. Furthermore, the target document schema does not use all the information that is provided by the source document schema. Both structures can be mapped to each other by using a structure mapping.

An example of when a value mapping is required is for the passenger class on a flight. In the source document, this information is coded by using a string, while in the target document, a decimal value is used. Another example of a value mapping would be the date format.

Using the Integration Builder graphical mapping editor, you can define structure mappings easily using Drag & Drop. You can then use a function to assign fields to each other from source and target structures that require a value mapping.

Interface Mappings in SAP XI

Use

Interface mappings register your mapping program for an interface pair in the Integration Repository. If you require a mapping at runtime, it is sufficient to select the interface mapping for the interface pair at configuration time (see: Defining Interface Determinations). The Integration Server uses the interface mapping to identify associated mapping programs for request messages, response messages, fault messages, or all three.

See also: Overview.

Features

Executing Multiple Mapping Programs for One Direction

By using an interface mapping you can execute multiple mapping programs consecutively for the transformation of a request or response message. In such cases, an interface mapping comprises multiple steps for which the following applies:

● The steps are executed in the sequence specified (from top to bottom). The result of the mapping program from the previous step is forwarded to the mapping program of the subsequent step.

● Each step can reference a mapping program that executes a 1:1, 1:n, n:1, or an m:n transformation. In the case of multi-mappings (1:n, n:1, or m:n), the previous step must create the same number of messages that the subsequent step expects.

● Multi-mappings use one envelope to put all messages in one structure. If one of the steps references a multi-mapping program, all subsequent steps must use the same envelope.

The mapping for a request message comprises two message mapping programs: one 1:1 transformation and one 1:n transformation. Since the latter message mapping uses the multi-mapping envelope for both the target message and the source message, the message mapping for the 1:1 transformation must also create a transformation result with a multi-mapping envelope.

You do not strictly need to divide up one direction of the whole mapping into different steps. However, this enables all the message formats in one system landscape to be mapped to a central message format, for example. This results in less mapping programs being required because you no longer need to be able to map all the different message formats to each other.

Activities

...

1. Create your interface mapping on the design maintenance screen of the Integration Builder (see also: Creating an Object).

You can also create multiple interface mappings for the same interface pair.

2. Enter the source and target interfaces that require a mapping of the request message, the response message, the fault message, or all three, in the table of the same name. The following restrictions apply:

○ If you want to use the interface mapping in a transformation step in an integration process, you must only specify abstract message interfaces. Furthermore, all objects (integration process, interface mapping, and all objects referenced by the interface mapping) must be in the same software component version. If you want to reference objects from underlying software component versions, you must access the objects from the Basis Objects branch (in the navigation tree or using an input help) (see also: Underlying Software Component Versions).

○ If you want to map multiple messages to each other by using a multi-mapping, you can only specify asynchronous interfaces (for further restrictions, see: Multi-Mappings). If any message interfaces are missing, you can also create them by using the functionCreate New Object ().

If the interface cannot be imported or cannot be created in the Integration Repository (in the case of an external adapter, for example), you must enter the interface names manually. However, it is not possible to check the technical name in this case.

3. To import the properties of the interfaces, choose Read Interfaces. The table in the lower area displays tab pages for the request message, response message, and if available, for the fault message, for each mode of the interfaces (either synchronous or asynchronous).

4. To develop an external mapping program, export the XSD schema of the respective request or response message as a zip file after you have imported the interfaces. The zip file can contain multiple schema files that reference each other, for example in a multi-mapping. In this case, the schema with the global message element has the name MainSchema.

5. To reference a mapping program for the respective message, you have the following options:

○ Select an existing mapping program from the Integration Repository by using the input help (). If this is a message mapping, the default setting of the input help only displays those message mappings that are found using the source and target message in the Integration Repository (in multi-mappings, the first source and target messages are used as the search criteria). However, you can also display any number of message mappings, for example, because you are constructing a mapping from several mapping programs with intermediate instances which have no message types.

○ You can create message mappings directly from the interface mapping. To do this, select the mapping type Message Mapping in the Type column. Position the cursor in the Name column and choose the function Create New Message Mapping () in the Mapping Program frame. The Integration Builder copies the specifications of the messages and their occurrence directly from the interface mapping.

An interface mapping can only reference mapping programs that belong to the same or an underlying software component version of the interface mapping. This ensures that the mapping program can be shipped together with the interface mapping (see: Software Logistics).

6. If you are not using a mapping for a fault message, you can execute multiple mapping programs in succession for request and response messages:

○ To insert an additional line for a mapping program, choose .

○ To delete the registration for a mapping program, choose .

At runtime, the mapping programs are executed from top to bottom.

7. Save the interface mapping.

Test Environment for Interface Mappings in SAP XI

Use

To check whether an interface mapping that you have defined functions at runtime, test the interface mapping on the Test tab page. Note the following restrictions:

● The Integration Builder cannot yet access the value-mapping table at the design stage. The results of accessing the value-mapping table are estimated as text output in the test results.

● The runtime constants of the mapping runtime are not set, or are set to dummy constant values.

You can execute a test run to test the mapping for the request message, response message, or fault message.

Prerequisites

The mapping programs to be tested must be available in the Integration Repository.

Message mappings must be complete so that the generated Java source code can be compiled.

To test mapping programs in the Repository, users require the role SAP_XI_ADMINISTRATOR_J2EE, SAP_XI_CONTENT_ORGANIZER_J2EE, SAP_XI_CONFIGURATOR_J2EE, or SAP_XI_DEVELOPER_J2EE.

Features

The features of the test environment are the same as those of the test environment for message mappings, except for the management of test cases.

Test Instances

To execute a message mapping, you require a test instance in XML that is valid according to your description of the source structure (in XSD or XML). The mapping editor generates this test instance automatically when you switch to the Test tab page for the first time.

General Functions for Test Instances

Function	Use
(Load XML Instance)	Loads an XML instance from a local file.
(Pretty Print)	Formats the XML document (indents, line breaks).

You can edit the XML instances to use them in different test instances:

● Using the editor for the text view. You can manually edit elements and attributes or their values here. Use CTRL C, CTRL X, and CTRL V respectively to copy, cut, and paste parts of an XML instance.

● Using the context menu in the (Tabular) Tree View. You can copy subtrees, delete nodes, and add elements and attributes. In the tabular tree view, you can also enter values for fields in the Value column.

Trace Level

At runtime of a message mapping you can create messages for a trace in user-defined functions (see: MappingTrace Object). Furthermore, if you have set the trace level to Debug, the message mapping runtime writes information for error analysis to the trace. To display trace messages in the text window for status messages in the test environment, you must select a trace level before the test.

Trace Level	Output
No Trace	No information about the trace is displayed.
Warning	Trace messages are displayed that you have written to the trace by means of the addWarning() method.
Information	Trace messages are displayed that you have written to the trace by means of the addInfo() method.
Debug	Trace messages from the mapping runtime and so on are displayed that you have written to the trace by means of the addDebugMessage() method.

Activities

...

1. Navigate to the Test tab page.

On the Test tab page, the left side displays the Source XML Instance and the right side displays the result of the transformation, that is, the Target XML Instance. The display options correspond to those of the structure overview in the message mapping editor.

2. If there is more than one direction, select one from the Direction list box (Request, Response, or Fault). If there is more than one source message in the fault direction, select one from the Source Message list box.

3. Load or generate a source instance, or enter an instance in the mapping editor, and use the functions described above to enhance the instance further.

If you have loaded an XML instance into the mapping editor, you use a copy of the instance and not the original when enhancing it in the mapping editor.

4. Select a trace level. To differentiate the trace outputs for mapping programs from those of the mapping runtime, use the outputs *** START APPLICATION TRACE *** and *** END APPLICATION TRACE ***.

5. To test your mapping using the XML instance, choose Execute Mapping (). If you are testing message mapping programs for the first time or have made changes since the last test, the Integration Builder compiles the generated Java source code before the test.

Result

The result of the transformation is displayed on the right-hand side. The Status Messages text frame displays the trace outputs and the transformation status, depending on the trace level. To delete all status messages, position the cursor within the text frame and from the context menu choose Delete Messages.

ABAP Mappings in SAP XI

Use

ABAP mappings are mapping programs in ABAP objects that customers can implement using the ABAP Workbench.

Prerequisites

Note the prerequisites in the sections Purpose and Integration as well as the Restrictions in Mapping Development with the ABAP Workbench.

Features

An ABAP mapping comprises an ABAP class that implements the interface IF_MAPPING in the package SAI_MAPPING. The interface has a method EXECUTE with the following signature:

Importing Parameter

Parameter	Meaning
SOURCE (Type XSTRING)	Source XML document
PARAM (Type Ref To IF_MAPPING_PARAM)	Parameter object for read access to runtime constants (see below)
TRACE (Type Ref To IF_MAPPING_TRACE)	Trace object for writing messages in the mapping trace (see below)

Exporting Parameter

Parameter	Meaning
RESULT (Type XSTRING)	Target XML document

Exception: CX_MAPPING_FAULT

Applications can decide themselves in the method EXECUTE how to import and change the source XML document. If you want to use the XSLT processor of SAP Web AS, you can use the ABAP Workbench to develop a stylesheet directly (see XSLT Mappings (ABAP Engine)) rather than using ABAP mappings.

Mapping Trace

You use the trace object to write messages in the mapping trace, which you can view in message monitoring. If using the method TRACE, you enter the trace level and the output message:

Trace Level	Meaning
0	No trace is written
1	Warnings are output
2	Warnings and error information are output
3	Warnings, error information, and debugging information are output

Alternatively, you can use the methods TRACE1, TRACE2, or TRACE3 to write messages for trace levels 1, 2, or 3 in the trace.

The trace level that you set for an Integration Engine pipeline determines which messages appear in monitoring. See also: Displaying/Changing Configuration Data.

Runtime Constants

In ABAP mapping you can read access message header fields. To do this, an object of type IF_MAPPING_PARAM is transferred to the EXECUTE method. The interface has constants for the names of the available parameters and a method GET, which returns the respective value for the parameter name. The constants are the same as in Java mappings, although the constant MAPPING_TRACE does not exist for ABAP mappings. Instead, the trace object is transferred directly using the parameter TRACE of the method IF_MAPPING~EXECUTE (see above).

Example: Accessing a Runtime Constant

Method IF_MAPPING~EXECUTE.

* Get mapping constant SENDER_SERVICE

data: l_sender_service type string.
l_sender_service = param->get( IF_MAPPING_PARAM=>SENDER_SERVICE ).

ENDMETHOD.