Mapping Lookups in SAP XI

Use

Mapping programs (message, Java, and XSLT mappings) are executed on the Integration Server, where they can access the global value-mapping table (see Executing Value Mappings) and mapping runtime constants. In addition, calls to other application systems are sometimes necessary to meet the following requirements:

● To get read access to application system data in the mapping program

● To call existing mapping routines in the application system

To fulfill these requirements, the mapping runtime provides an API for mapping lookups. The API can be executed by message, Java, and XSLT mappings on the Application Server Java.

Integration

When a mapping program is executed on the Integration Server, the lookup API calls the required application system by using the central Adapter Engine.

The call is synchronous. This means that the adapter called returns the result of the call immediately (not represented in the graphic).

Programming and Configuration

Developers pass the lookup API the name of a communication channel in the mapping program. Consultants later use this name to configure the call for the adapter in the Integration Directory. This name must be documented in the relevant guide for the application.

If the mapping lookup is used to read data from a database table, the name of this table needs to be known. The name can be set dynamically, for example, if the sender of the message writes it in the payload. The mapping program then reads the table name from the payload and uses it for the call using the lookup API.

Prerequisites

The mapping lookup API is available as of SAP NetWeaver ’04 SPS13.

The API for mapping lookups supports access using the RFC, JDBC, and SOAP adapters. If you want to use a third-party adapter for a mapping lookup in an application system, the adapter must fulfill the following requirements:

● The adapter must support synchronous calls.

● The adapter must not depend on information from a receiver agreement. If the adapter depends on this information, processing of the mapping lookup is terminated.

You can only execute mapping lookups using the central Adapter Engine.

Features

To execute calls to an application system by using the lookup API, developers use either a generic or special lookup API.

Generic Lookup API

In the case of generic access, before executing the lookup, developers first need to both build the payload that the adapter expects and parse the result payload themselves.

To access an application system generically, developers use the SystemAccessor class. For generic calls, developers of a method must pass a stream with the payload, which is then sent to the adapter. The result of the call is a payload object, which you can use to both read the payload as a stream and parse the payload.

The generic lookup API is part of the mapping API (see LookupService class in the Javadoc documentation). For more information about these APIs, see SAP Developer Network at https://www.sdn.sap.com/irj/sdn/javadocs (SDN user required).

You can obtain the schema to call an RFC by simply importing the RFC into the Integration Repository. (See Importing IDocs and RFCs.)

Special Lookup API

For access using the special lookup API, developers do not require any knowledge of the structure of the payload. Instead, they pass the API string commands that are to be executed in the application system called.

Currently, there is one special lookup API for the JDBC adapter. To use this API, developers use the DataBaseAccessor class instead of the SystemAccessor class.

The special lookup API is part of the mapping API (see the getDataBaseAccessor method of the LookupService class in the Javadoc documentation). For more information about these APIs, see SAP Developer Network at https://www.sdn.sap.com/irj/sdn/javadocs (SDN user required).

Activities

...

1. Develop your mapping lookup routine in Java using the lookup API. You can use the routine in the following mapping programs:

○ In user-defined functions of message mappings

○ In Java or XSLT mappings that you import as archives into the Integration Repository. (See Imported Archives (XSLT/Java).) To enable a call to the lookup routine from XSLT mappings, use XSLT mappings with Java enhancement.

2. Document which adapter is called and which receiver channel is used to do so during the mapping lookup.

3. To test the lookup routine using an interface mapping, the receiver channel must be configured in the Integration Directory, and the runtime components of the Integration Server must be installed. If these requirements are not fulfilled, the mapping terminates with an error message.