User-Defined Functions in XI Message Mappings

Use

If the standard functions for a target-field mapping do not fulfill your requirements, or if the graphical representation becomes unclear due to the complexity of the mapping, you have the option of creating your own user-defined functions. You can create Java source text in this function. The function is included in the Java coding that is generated for the message mapping as a Java method.

Make sure you read the implementation considerations in Java Mapping, which also apply to user-defined functions in message mappings.

A user-defined function is only visible in the message mapping in which you created it. You can insert the function in the data-flow editor by using the function category User-Defined, just like a standard function.

Integration

You can use your Java programs from imported archives in user-defined functions if the Java programs are located in the same, or an underlying software component version as the message mapping.

Prerequisites

You have created a message mapping and have loaded an XML structure for both the source and the target structure.

Features

Depending on which values are available in the cache for a user-defined function, different functions are available:

· Simple Functions (Cache = Value)
This function type can process individual input values of a field for each function call. Therefore, simple functions expect strings as input values and return a string.

· Enhanced Functions (Cache = Context or Cache = Queue)
This function type can process multiple input values of a field for each function call. Before you call the function, you can either import all the field values of a context or the whole queue for the field in an array. For more information, see Advanced User-Defined Functions.

Note that when dealing with large messages, saving the entire queue in the cache requires a lot of memory at runtime. In such cases it is therefore better to work with contexts.

¡ For both function types you can use the following objects in the source code:

Objects in Simple and Advanced Functions

Object	Use
Container	This object enables you to cache the values that you want to read again when you next call the same user-defined function.
GlobalContainer	This object enables you to cache the values that you want to read again when you next call any user-defined function that is in the same message mapping.
MappingTrace	This object enables you to transfer information for the mapping trace during mapping to a container that can be viewed by users in the message monitoring.

Activities

1. To create a new user-defined function, choose Create New Function () in the data-flow editor at the bottom of the screen, on the left-hand side.

2. Specify the attributes of the new function in the subsequent window:

Name:
Technical name of the function. The name is displayed in the function chooser and on the data-flow object.

Description:
Description of how the function is used.

Cache:
Function type (see above).

Arguments:
In this table, you specify the number of input values the function can process, and name them. All functions are of type String.

3. In the subsequent window, you can create Java source code:

a. You can import Java packages to your methods from the Imports input field, by specifying them separated by a comma or semi-colon:

You do not need to import the packages java.lang.*, java.util.*, java.io.*, and java.lang.reflect.* since all message mappings require these packages and therefore import them. You should be able to access standard JDK and J2EE packages of the SAP Web Application Server by simply specifying the package under Import. In other words, you do not have to import it as an archive into the Integration Repository. You can also access classes of the SAP XML Toolkit, the SAP Java Connector, and the SAP Logging Service (see also: Runtime Environment (Java-Mappings)).

In addition to the standard packages, you can also specify Java packages that you have imported as archives and that are located in the same, or in an underlying software component version as the message mapping.

b. Create your Java source text in the editor window or copy source text from another editor.

4. Confirm with Save and Close.

5. User-defined functions are limited to the message mapping in which you created the function. To save the new function, save the message mapping.

6. To test the function, use the test environment.

The new function is now visible in the User-Defined function category. When you select this category, a corresponding button is displayed in the function chooser pushbutton bar. To edit, delete, or add the function to the data-flow editor, choose the arrow next to the button and select from the list box displayed.