SAP Exchange

Infrastructure 3.0 -
Graphical Mapping
Introduction and New
Features

William Li

SAP Labs, LLC

 Agenda
Concepts / Overview
Test/Debugging Environment
Standard Functions
n Function Usage
n Simple Function Examples
n Node Function Examples

Introduction to Most–Common Java Usage

User-defined Functions
n Usage
Advanced User–Defined Functions
n Usage
n ResultList, Container Object, GlobalContainer Object, MappingTrace
Object
Message Mapping “Patterns”
n Summarization
n Sequence Number Generation
n Duplicating Subtrees

Multi–Mappings
Mapping Templates
Summary

 SAP AG 2003, Title of Presentation, Speaker Name / 2

 Agenda
Concepts / Overview
Test/Debugging Environment
Standard Functions
n Function Usage
n Simple Function Examples
n Node Function Examples

Introduction to Most–Common Java Usage

User-defined Functions
n Usage
Advanced User–Defined Functions
n Usage
n ResultList, Container Object, GlobalContainer Object, MappingTrace
Object
Message Mapping “Patterns”
n Summarization
n Sequence Number Generation
n Duplicating Subtrees

Multi–Mappings
Mapping Templates
Summary

 SAP AG 2003, Title of Presentation, Speaker Name / 3

 Concepts - General Mapping Types

Mapping
n Transformation from one message structure to another
n Transformation of one key value to another

Value
<hh:book-flight xmlns:hh="..."> Mapping
<hh:customer>
<hh:first-name>Micheal</hh:first-name> <ak:BookFlight xmlns:ak="...">
<hh:surname>Moore</hh:surname> <ak:Date>22.11.2001</ak:Date>
</hh:customer> <ak:Flight>087</ak:Flight>
<hh:booking-data> <ak:Passenger>Micheal Moore</ak:Passenger>
<hh:airline>Airline Kingdom</hh:airline>
Structure Mapping <ak:Class>2</ak:Class>
<hh:connection>AK087</hh:connection> <ak:Agency>Happy Holiday</ak:Agency>
<hh:date>2001-11-22</hh:date> </ak:BookFlight>
<hh:class>business</hh:class>
</hh:booking-data>
</hh:book-flight>

 SAP AG 2003, Title of Presentation, Speaker Name / 4

 Stateless Processing Model – Logical View

Determination of technical
Logical receiver & interface Transformation of sender
connectivity information
determination based on format & values into
(address, transport protocol,
business level rules receiver format & values
adapter, ...)

Integration Server
FROM application systems or adapters

TO application systems or adapters

XM L M essage XM L M essage XM L M essage XM L M essage

Envelope: Envelope: Envelope: Envelope:

- Sender - Receiver - Receiver - Receiver
- Sender IF - Receiver IF - Receiver IF Address + ...
- ... - ... - ... Physical - ...
Logical
Mapping Address
Routing
Payload: Payload: Payload: Resolution Payload:

Sender Sender Receiver Receiver

Docum ent Document Document Document

Integration
Routing Rules M apping Relations W eb Services
Directory

Integration
M appings
Repository

Technical activities (sending, receiving, queuing,...) omitted

 SAP AG 2003, Title of Presentation, Speaker Name / 5
 Concepts - Relate Mapping Programs to Interfaces

Integration Repository
Sender Receiver
Message Interface Interface Mapping(s) Message Interface
Request

Message Mapping
XSLT Mapping
Request Java Mapping Request
Message Type ABAP Mapping
Message Type
Response

Message Mapping
XSLT Mapping
Response Java Mapping Response
Message Type ABAP Mapping Message Type

Message Mapping
XSLT Mapping
Fault

Fault Java Mapping Fault

Message Type ABAP Mapping Message Type

 SAP AG 2003, Title of Presentation, Speaker Name / 6

 Concepts - Mapping in SAP XI

Message Mapping
n Designed by using the graphical mapping editor of Integration
Builder
n Result: Generated Java Code.
n NOT memory–intensive, can “theoretically” handle GB–sized
messages

Imported Archives
n Import externally defined mapping programs into repository
n Java mapping:
Implemented by using a specific interface
n XSLT mapping:
u Runtime supports XSLT processor
u Java methods can be called from within a Style Sheet

ABAP Workbench
n ABAP Mappings in ABAP objects
n XSLT Mappings (ABAP Engine)
You can execute mapping programs in a sequence
(Only for a request or a response message)

 SAP AG 2003, Title of Presentation, Speaker Name / 7

 Overview – Message Mapping

Use
n Design structure mapping between any 2 XML structures
n Connect to “value” mapping
n Generates java source code and jar files to be used during
runtime.
n Can load the following into the structure overview:
u A schema from the Integration Repository
l Message Types
l External Definitions
l Imported Objects (RFCs and IDOCs)
u XML or XSD files from a local file (import and include are
ignored in XSD)

 SAP AG 2003, Title of Presentation, Speaker Name / 8

 Overview – Message Mapping Functions

Standard Functions
n E.g. string processing, number/date formatting, boolean, …

Value Mapping

Node functions

User-defined functions
n Java method

 SAP AG 2003, Title of Presentation, Speaker Name / 9

 Icon Status Display

Icon Types
Icon Meaning
Attribute

Element

Element with more than 1 occurance

Icon Colors
Color Meaning
White Optional attribute or element not assigned
Red Attribute or element must be assigned to complete the
mapping
Yellow Attribute or element has already been assigned but the
corresponding mapping in the data-flow editor is not
complete
Green Mapping to target field complete

 SAP AG 2003, Title of Presentation, Speaker Name / 10

 Overview –Mapping Editor

 SAP AG 2003, Title of Presentation, Speaker Name / 11

 Overview – Assignment of Fields

Double click on a
Double click on Double click on a white/red field
an any field green/yellow field =
= = insert field into
insert field into navigate to data-flow editor
data-flow editor target field mapping

drag&drop
drag&drop drag&drop

 SAP AG 2003, Title of Presentation, Speaker Name / 12

 Overview – Assign Source/Target Message Types

There are 3 ways message types can be assigned to the Message

Mapping.
1. By using an existing object already created in the Integration Repository
(e.g. Message Type, External Definitions)
2. By using an RFC or IDoc meta data imported from SAP
3. By importing XML or XSD files from local file system

 SAP AG 2003, Title of Presentation, Speaker Name / 13

 Overview – Data–Flow Editor

Delete
Delete Current
Floating Mapping
Lay Out
Objects
Mapping

Select
Function
Category
Define Select
User Function
Function

 SAP AG 2003, Title of Presentation, Speaker Name / 14

 Overview – Data–Flow Editor – Example

 SAP AG 2003, Title of Presentation, Speaker Name / 15

 Overview – Text Preview

All target
field
mappings

 SAP AG 2003, Title of Presentation, Speaker Name / 16

 Overview – Dependencies

Dependencies

All mappings or
mappings of two selected
subnodes are displayed

 SAP AG 2003, Title of Presentation, Speaker Name / 17

 Agenda
Concepts / Overview
Test/Debugging Environment
Standard Functions
n Function Usage
n Simple Function Examples
n Node Function Examples

Introduction to Most–Common Java Usage

User-defined Functions
n Usage
Advanced User–Defined Functions
n Usage
n ResultList, Container Object, GlobalContainer Object, MappingTrace
Object
Message Mapping “Patterns”
n Summarization
n Duplicating Subtrees
n Table/Value Lookup (within source, not external)
n Tree–Reversal
Multi–Mappings
Mapping Templates
Summary

 SAP AG 2003, Title of Presentation, Speaker Name / 18

 Test/Debugging Environment

A completed Message Mapping can be tested by using the “Test” tab.

Loads an XML Search node name
instance from a in the Tabular Tree
local file. View

Dropdown
XML provides the
Execute document creation and
Tabular
Mapping view saving of test
Tree View
cases
Prerequisites
1. The defined message mapping must be complete. This means that each mandatory
target field must be assigned to one or more source fields.
2. There must not be any unassigned arguments when using functions.

 SAP AG 2003, Title of Presentation, Speaker Name / 19

 Test/Debugging Environment
Editing the XML instances to use in test cases:

Enter test
data

Using the context menu in the Using the editor for the XML view,
(Tabular) Tree View, you can copy you can manually edit elements
sub-trees, delete nodes, and add and attributes or their values
elements and attributes. In the here. Use CTRL C, CTRL X, and
Value column in the tabular tree CTRL V respectively to copy, cut,
view you can also enter values for and paste parts of an XML
fields. instance.

 SAP AG 2003, Title of Presentation, Speaker Name / 20

 Test/Debugging Environment
Using the “Display Queue” to examine each step of the mapping:

Note:
The “context”
display and
usage in the
queues will be
discussed in
later slides.

 SAP AG 2003, Title of Presentation, Speaker Name / 21

 Agenda
Concepts / Overview
Test/Debugging Environment
Standard Functions
n Function Usage
n Simple Function Examples
n Node Function Examples

Introduction to Most–Common Java Usage

User-defined Functions
n Usage
Advanced User–Defined Functions
n Usage
n ResultList, Container Object, GlobalContainer Object, MappingTrace
Object
Message Mapping “Patterns”
n Summarization
n Duplicating Subtrees
n Table/Value Lookup (within source, not external)
n Tree–Reversal
Multi–Mappings
Mapping Templates
Summary

 SAP AG 2003, Title of Presentation, Speaker Name / 22

 Standard Functions: Introduction

n Most data-flow objects have two or three inbound channels on the left-
hand side, and one outbound channel on the right-hand side.

n If functions are shaped as rhombuses or triangles.

n There are also conversion functions with one inbound and outbound
channel and functions that get a value without making any entries.

n Standard functions that require additional specifications are indicated

with a star ( ). To call the dialog for Function Properties, double click
the data-flow object.

 SAP AG 2003, Title of Presentation, Speaker Name / 23

 Simple Standard Functions: concat

Function category: Text

Source Message Mapping Target Message
<?xml version="1.0" <?xml version="1.0"
encoding="UTF-8" ?> encoding="UTF-8" ?>

<Customer> <Contact>
<firstname> <name>
Harry Harry Potter
</firstname> </name>
<surname> </Contact>
Potter
</surname>
</Customer>

concat properties
Delimiter=“ “

 SAP AG 2003, Title of Presentation, Speaker Name / 24

 Simple Standard Functions: substring

Function category: Text

Source Message Mapping Target Message
<?xml version="1.0" <?xml version="1.0"
encoding="UTF-8" ?> encoding="UTF-8" ?>

<Customer> <Contact>
<customerID> <customerNo>
0123456789-181170 0123456789
</customerID> </customerNo>
</Customer> </Contact>

substring properties
start from: 0
count: 10

Position count for all text functions start at 0!

 SAP AG 2003, Title of Presentation, Speaker Name / 25

 Simple Standard Functions: DateTrans

Function category: Date

Source Message Mapping Target Message
<?xml version="1.0" <?xml version="1.0"
encoding="UTF-8" ?> encoding="UTF-8" ?>

<Customer> <Contact>
<custBirthday> <birthday>
181170 11/18/1970
</custBirthday> </birthday>
</Customer> </Contact>

DateTrans properties
src Format: ddMMyy
dst Format: MM/dd/yyyy

•uses standard Java date template

 SAP AG 2003, Title of Presentation, Speaker Name / 26

 Function Categories

Arithmetic: add, substract, equalsA, abs, sqrt, sign, sqrt, etc.

Boolean: And, Or, Not, Equals, notEquals, if, ifWithoutElse

Constants: Constant, CopyValue, sender, receiver

Conversions: FixValues, Value mapping

Date: currentDate, DateTrans, DateBefore, DateAfter, CompareDate

Node Functions: createIf, removeContexts, replaceValue, exists,

SplitByValue, collapseContexts

Statistic: sum, average, count

Text: substring, concat, equalsS, indexOf, lastIndexOf, compare, etc.

(The functions marked in blue will be explored in detail.)

 SAP AG 2003, Title of Presentation, Speaker Name / 27

 Constant Function – CopyValue
Use CopyValue() to copy a repeating value’s position in the source structure and assign it
to a target field.

Example:

Result:

 SAP AG 2003, Title of Presentation, Speaker Name / 28

 Node Function – createIf
Use createIf() to create a tag in the target structure using a condition.

Example: Depending on the value of type (internal or external), the target tag either
internalRequest or externalRequest will be created.

 SAP AG 2003, Title of Presentation, Speaker Name / 29

 Node Function– exists
Use exists() to determine whether a particular source field exists in the XML instance to be
processed. If does, exists() returns true, otherwise, false.

Example: In the source, description is optional. However, in the target, description is

mandatory.

 SAP AG 2003, Title of Presentation, Speaker Name / 30

 Node Functions – Contexts

Context Change
n Message mapping works
internally by using queues
n If no further elements are
imported at a particular hierarchy
level, a Context Change is
inserted in the queue
n Use node functions to handle
changes in the message
hierarchy.

removeContexts
n deletes all context changes of a
queue

SplitByValue
n insert additional context changes
in a queue

 SAP AG 2003, Title of Presentation, Speaker Name / 31

 Node Functions – removeContexts (I)

With removeContexts

Source Message Mapping Target Message

<?xml version="1.0" <?xml version="1.0"
encoding="UTF-8" ?> encoding="UTF-8" ?>

<Test_Out_Remove> <Test_In_Remove>
<header name=“A"> <item>A.one</item>
<item>A.one</item> <item>A.two</item>
<item>A.two</item> <item>A.three</item>
<item>A.three</item> <item>B.one</item>
</header> <item>B.two</item>
<header name="B"> </Test_In_Remove
<item>B.one</item>
<item>B.two</item>
</header>
</Test_Out_Remove>

§use removeContext() to delete the parent context of an

element.

 SAP AG 2003, Title of Presentation, Speaker Name / 32

 Node Functions – removeContexts (II)

Without removeContexts

Source Message Mapping Target Message

<?xml version="1.0" <?xml version="1.0"
encoding="UTF-8" ?> encoding="UTF-8" ?>

<Test_Out_Remove> <Test_In_Remove>
<header name=“A"> <item>A.one</item>
<item>A.one</item> <item>A.two</item>
<item>A.two</item> <item>A.three</item>
<item>A.three</item> </Test_In_Remove>
</header>
<header name="B">
<item>B.one</item>
<item>B.two</item>
</header>
</Test_Out_Remove>

 SAP AG 2003, Title of Presentation, Speaker Name / 33

 Node Function – removeContext

Use removeContext() to delete all the higher contexts for an element. This deletes all
higher hierarchy levels, so that all elements of the target queue are assigned to a root
element of the source queue.

 SAP AG 2003, Title of Presentation, Speaker Name / 34

 Node Function– SplitByValue
SplitByValue() is the counterpart to removeContexts(): Instead of deleting a context, you can
insert a context change in the source value queue.

Only this number of elements will be created. If the number

in the source is less, error exception will occur.

 SAP AG 2003, Title of Presentation, Speaker Name / 35

 Node Function – collapseContexts

Using collapseContexts() replaces all values of all contexts with an empty

string:

This can be useful if each time an upper-level node is to be created if a

lower-level node exists, for example. The function is useful in
combination with the function SplitByValue().

 SAP AG 2003, Title of Presentation, Speaker Name / 36

 Node Function – collapseContexts (cont.)
To avoid previous example’s limitation of just using SplitByValue(), when exact number of
elements had to be provided.

Example when source

has only 1 element.

Example when
source has multiple
elements.

 SAP AG 2003, Title of Presentation, Speaker Name / 37

 Agenda
Concepts / Overview
Test/Debugging Environment
Standard Functions
n Function Usage
n Simple Function Examples
n Node Function Examples

Introduction to Most–Common Java Usage

User-defined Functions
n Usage
Advanced User–Defined Functions
n Usage
n ResultList, Container Object, GlobalContainer Object, MappingTrace
Object
Message Mapping “Patterns”
n Summarization
n Duplicating Subtrees
n Table/Value Lookup (within source, not external)
n Tree–Reversal
Multi–Mappings
Mapping Templates
Summary

 SAP AG 2003, Title of Presentation, Speaker Name / 38

 Intro to Java Usage

Using Java in user functions will extend the capability of Message

Mapping and, many time, will be necessary.

To effectively use Java in Message Mapping:

n Do not need to be an expert Java programmer
n Should be familiar with classes in packages:
u java.lang.* (e.g. String)
u java.util.* (e.g. Vector, Collections)

n Should be familiar with String and array operations:

u length() and length
u compare (do not use ==, instead, use equals())

n Should be familiar with for…next and while loops.

 SAP AG 2003, Title of Presentation, Speaker Name / 39

 Intro to Java Usage – String

String
n All parameters passed in user functions are as String or array of
String:
u Single String variable is passed in simple user function
u String array is passed in advanced user function
n String has the following useful methods:
u substring
u concat
u equals and equalsIgnoreCase
u length
n String comparisons:
u DO NOT use:
String a;
if (a == “PRODUCT”) …
u DO use:
String a;
if (a.equals(“PRODUCT”)) …
or
if (a.equalsIgnoreCase(“PRODUCT”)) …

 SAP AG 2003, Title of Presentation, Speaker Name / 40

 Intro to Java Usage – arrays

Arrays
n Parameters in advanced user functions are passed as arrays.
n Most common processing of arrays is the use of for…next:
String[ ] a;
for (int i=0; i<a.length; i++) {
if (a[i].equals(“PRODUCT”) …
…..
}

Integer
n Use Integer class to convert integer to String
int i = 100;
String a = Integer.toString(i);

 SAP AG 2003, Title of Presentation, Speaker Name / 41

 Agenda
Concepts / Overview
Test/Debugging Environment
Standard Functions
n Function Usage
n Simple Function Examples
n Node Function Examples

Introduction to Most–Common Java Usage

User-defined Functions
n Usage
Advanced User–Defined Functions
n Usage
n ResultList, Container Object, GlobalContainer Object, MappingTrace
Object
Message Mapping “Patterns”
n Summarization
n Duplicating Subtrees
n Table/Value Lookup (within source, not external)
n Tree–Reversal
Multi–Mappings
Mapping Templates
Summary

 SAP AG 2003, Title of Presentation, Speaker Name / 42

 User-Defined Functions – Overview

User–Define Functions:
n Functional enhancements: if standard functions do
not fulfill requirements
n Is only visible in the message mapping in which you
created it
n Can use Java programs from imported archives of
the same software component version
n Use just like standard functions

 SAP AG 2003, Title of Presentation, Speaker Name / 43

 User-Defined Functions – Overview

User–Defined Function types:

n Simple functions, which can process individual
field input values for each function call. Simple
functions, therefore, expect strings as input values
and return a string.
n Advanced functions, which can process non–single
string field input values (or arrays) for each
function call. You can pass either all field values of
a context or the whole queue for the field in an
array when calling the function. Each input field is
passed as an array of String. Returned values are
stored in a String array, ResultList.

 SAP AG 2003, Title of Presentation, Speaker Name / 44

 User-Defined Functions – Overview

Objects available to 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.

 SAP AG 2003, Title of Presentation, Speaker Name / 45

 User-Defined Functions – Editor

Define
User
Function

 SAP AG 2003, Title of Presentation, Speaker Name / 46

 User-Defined Simple Function

n Select Simple Function

n Single return value is of type java.lang.String

n Import Java packages if required,

e.g. com.company.sap.xi.mytools.*; com.company.sap.xi.myutils.*;

 SAP AG 2003, Title of Presentation, Speaker Name / 47

 Agenda
Concepts / Overview
Test/Debugging Environment
Standard Functions
n Function Usage
n Simple Function Examples
n Node Function Examples

Introduction to Most–Common Java Usage

User-defined Functions
n Usage
Advanced User–Defined Functions
n Usage
n ResultList, Container Object, GlobalContainer Object, MappingTrace
Object
Message Mapping “Patterns”
n Summarization
n Duplicating Subtrees
n Table/Value Lookup (within source, not external)
n Tree–Reversal
Multi–Mappings
Mapping Templates
Summary

 SAP AG 2003, Title of Presentation, Speaker Name / 48

 Advanced User–Defined Functions

Advanced user–defined functions can access more than just individual

values. A complete context or an entire queue can be accessed.

Queue
Context

Message Mapping works by using queues. There is a queue for each

element.

 SAP AG 2003, Title of Presentation, Speaker Name / 49

 User-Defined Advanced Function

n Select Advanced Function

n Values to be returned are in the object result

Input is an array of String result contains output

n Import Java packages if required,

e.g. com.company.sap.xi.mytools.*; com.company.sap.xi.myutils.*;

 SAP AG 2003, Title of Presentation, Speaker Name / 50

 Advanced User–Defined Functions

Advanced user–functions can import either just one context or the

complete queue into input String arrays.

To import the complete queue, check the “Cache Entire Queue”

checkbox in the function editor.

Working with Contexts or Queues

Information in Cache Implications

Context Do not have identifiable context
change.
Queue Contains context change indicator.
Much more memory intensive.

Context changes at the beginning and end of the context or queue are implicit and
cannot identified.

 SAP AG 2003, Title of Presentation, Speaker Name / 51

 Advanced User–Defined Functions
A queue can have the following entries:

Value Meaning

(empty string) In the queue, there is an entry with an empty string

each time the field appears in the XML instance, e.g.
<A />, <root />.

(string) Value of a value field, e.g. <item>2</item>

ResultList.CC Constant that shows a context change.

ResultList.SUPPRESS Constant that causes a field and its sub node to be

ignored during processing.

Special structures can be created by adding or removing context changes, e.g. by

using functions, SplitByValue() or removeContexts() or manually inserting the
constant.

 SAP AG 2003, Title of Presentation, Speaker Name / 52

 Advanced User–Defined Functions – ResultList Object

This object is used in advanced user–defined functions to return the

result of the function. It can be used to either return a queue or to
return the context of a queue.

Methods of the ResultList Object

Method Use
void addValue(String value); Append a value to the results list.

void addContextChange(); Appends a context change to the list. This is the

same as append ResultList.CC by using addValue().

void addSuppress(); Appends the constant ResultList.SUPPRESS to the

list.

void clear(); Deletes all previously appended values from the list.

 SAP AG 2003, Title of Presentation, Speaker Name / 53

 Advanced User–Defined Functions – ResultList Object

The ResultList.CC constant can be used to find context changes

in the input array, when the “Cache Entire Queue” is checked.
For example:

if ( a[index].equals(ResultList.cc) ) …

Note:
n When the input array contains only context, no context change
exists.
n When the input array contains the entire queue, context changes can
exist, but not at the beginning or end of the queue.

 SAP AG 2003, Title of Presentation, Speaker Name / 54

 Advanced User–Defined Functions – Container Object

Use Container object to:

Cache (or save) data which can be accessed again when the user–function is
called again.

Methods Use
void setParameter(String Saves the obj object under the name parName in a
parName, object obj); container for a user–specific function.

Object getParameter (String Returns the parameter that was saved under the parName
parName); name in this user–specific function by using the
setParameter method. If no such parameter exists, null
is returned.
MappingTrace getTrace(); Returns a MappingTrace object with which messages can
be written to the mapping trace in the monitor. (to be
discussed)
GlobalContainer Returns a GlobalContainer object with which data can be
getGlobalContainer(); saved and read by any user–defined functions in the
same message mapping. (to be discussed)
Java.util.Map Returns a map with the mapping runtime constants. (to
getTransformationParameters(); be discussed)

 SAP AG 2003, Title of Presentation, Speaker Name / 55

 Advanced User–Defined Functions – Container Object

Use Container object:

To access mapping runtime constants, e.g. sender or receiver.

n The constants are attributes of

com.sap.aii.mapping.api.StreamTransformationConstants. Therefore, it must
be imported in the user–defined function.
n The following values can be obtained: PROCESSING_MODE, MESSAGE_ID,
REF_TO_MESSAGE_ID, TIME_SENT, INTERFACE, INTERFACE_NAMESPACE,
SENDER_PARTY, SENDER_SERVICE, RECEIVER_NAME,
RECEIVER_NAMESPACE, RECEIVER_PARTY, RECEIVER_SERVICE, etc.
(additional ones can be found in the Java Mapping documentation)
n Usage example:
String constant;
java.util.Map map;
// get constant map
map = container.getTransformationParameters();
constant = (String) map.get(
StreamTransformationConstants.INTERFACE_NAMESPACE);
return constant;
(during design time, test string is used.)

 SAP AG 2003, Title of Presentation, Speaker Name / 56

 Advanced User–Defined Functions – GlobalContainer
Object

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.
Note that the sequence in which user-defined functions are called is predefined.
It depends on the position of the target fields that the function was assigned to.

To get a global container object, call the getGlobalContainer() method

for the Container Object.

Methods Use

void setParameter(String parName, Saves the obj object under the name parName in
object obj); a global container for a user–specific function.

Object getParameter (String Returns the parameter that was saved under the
parName); parName name in this user–specific function by
using the setParameter method. If no such
parameter exists, null is returned.

 SAP AG 2003, Title of Presentation, Speaker Name / 57

 Advanced User–Defined Functions – MappingTrace Object

This object enables the writing of messages to the mapping trace in the
message monitoring (SXMB_MONI).
Trace Method Use
Level
0 No trace

1 void addInfo(String message); Add message with trace

level info.
2 void addWarning(String message); Add message with trace
level warning.
3 void addDebugMessage(String Add message with trace
message); level debug.

Trace level can be set in the Pipeline configuration. Each trace level will include messages
from lesser trace levels, e.g. debug will include messages from warning and info.

Usage example:
MappingTrace trace = container.getTrace();
trace.addInfo(“This is a trace message.”);

 SAP AG 2003, Title of Presentation, Speaker Name / 58

 Agenda
Concepts / Overview
Test/Debugging Environment
Standard Functions
n Function Usage
n Simple Function Examples
n Node Function Examples

Introduction to Most–Common Java Usage

User-defined Functions
n Usage
Advanced User–Defined Functions
n Usage
n ResultList, Container Object, GlobalContainer Object, MappingTrace
Object
Message Mapping “Patterns”
n Summarization
n Sequence–Number Generation
n Duplicating Subtrees

Multi–Mappings
Mapping Templates
Summary

 SAP AG 2003, Title of Presentation, Speaker Name / 59

 Mapping “Patterns”

Mapping “patterns” are some of the common mapping

requirements we found in the past which XSLT was used,
because we did not think that Message Mapping provided the
functionality

n Summarization
n Sequence–Number Generation
n Duplicating Subtrees

 SAP AG 2003, Title of Presentation, Speaker Name / 60

 Mapping “Patterns” – Summarization
Summarization is when we try to consolidate detailed information into total/subtotals and
counts.

The count and sum functions will act on the content of a context. Therefore, the context of
the group to be summarized must be selected appropriately.

Example:

Source: Order details containing

customer, order numbers and
order amount

Target: Total and count the order

by each customer and a summary
of all orders

 SAP AG 2003, Title of Presentation, Speaker Name / 61

 Mapping “Patterns” – Summarization

 SAP AG 2003, Title of Presentation, Speaker Name / 62

 Mapping “Patterns” – Summarization

Mapping Result:

 SAP AG 2003, Title of Presentation, Speaker Name / 63

 Mapping “Patterns” – Sequence–Number Generation

There are situations when sequence numbers had to be generated based

on the number of occurrences of the source data. This is frequently
used during mapping to SAP IDocs or BAPIs when item number, which is
no available from the source, had to be added.

Example:

Source: Order information.

Target: Two complex elements

had to be populated from the
source. Each one contains a
sequence number which matches
the position of the data in the
source.
Sequence number to be generated.
 SAP AG 2003, Title of Presentation, Speaker Name / 64
 Mapping “Patterns” – Sequence–Number Generation

There are two ways the sequence number can be generated.

1. Use Advanced User–Defined function to generate the

sequence number all at once.

2. Use Simple User–Defined function to generate the sequence

number for each occurrence separately, keeping track of the
sequence number value previously generated.

 SAP AG 2003, Title of Presentation, Speaker Name / 65

 Mapping “Patterns” – Sequence–Number Generation

1. Use Advanced User–Defined function to generate the sequence

number all at once.

The java function creates the sequence number all at once based on the number of
elements in the source.

The sequence numbers are written to the ResultList object.

 SAP AG 2003, Title of Presentation, Speaker Name / 66

 Mapping “Patterns” – Sequence–Number Generation
1. Use Advanced User–Defined function to generate the sequence
number all at once.

 SAP AG 2003, Title of Presentation, Speaker Name / 67

 Mapping “Patterns” – Sequence–Number Generation

1. Use Advanced User–Defined function to generate the sequence

number all at once.
Test Results:

 SAP AG 2003, Title of Presentation, Speaker Name / 68

 Mapping “Patterns” – Sequence–Number Generation

2. Use Simple User–Defined function to generate the sequence number

for each occurrence separately, keeping track of the sequence
number value previously generated.

The sequence number is stored in

the container object. Each time it
is retrieved, incremented and
saved.

Note: There is no input required.

 SAP AG 2003, Title of Presentation, Speaker Name / 69

 Mapping “Patterns” – Sequence–Number Generation

2. Use Simple User–Defined function to generate the sequence number

for each occurrence separately, keeping track of the sequence
number value previously generated.

We cannot display the queue to examine the result of the mapping.

 SAP AG 2003, Title of Presentation, Speaker Name / 70

 Mapping “Patterns” – Sequence–Number Generation

2. Use Simple User–Defined function to generate the sequence number

for each occurrence separately, keeping track of the sequence
number value previously generated.

 SAP AG 2003, Title of Presentation, Speaker Name / 71

 Mapping “Patterns” – Duplicating Subtrees

Even if elements are shown to occur more than once in the XML instance
according to XML Schema Definition, they are only displayed once in the structure
overview.

To assign source field(s) to multiple positions of an element in the target

structure, the element or the entire subree can be duplicated (copied) using the
context menu in the target structure.

Example:
Source: Accounting information with
adjustment type and amount.

Target: Two CurrencyAmt’s are to

be created. One is to credit one
account. The other is to debit
another account. The amount will
either be positive or negative
depending on the ADJTYPE.

 SAP AG 2003, Title of Presentation, Speaker Name / 72

 Mapping “Patterns” – Duplicating Subtrees

The subtree “CurrencyAmt” must be duplicated first. This will create 2

CurrencyAmt’s. One for credit, and one for debit.

 SAP AG 2003, Title of Presentation, Speaker Name / 73

 Mapping “Patterns” – Duplicating Subtrees

 SAP AG 2003, Title of Presentation, Speaker Name / 74

 Mapping “Patterns” – Duplicating Subtrees

Mapping Results:

 SAP AG 2003, Title of Presentation, Speaker Name / 75

 Agenda
Concepts / Overview
Test/Debugging Environment
Standard Functions
n Function Usage
n Simple Function Examples
n Node Function Examples

Introduction to Most–Common Java Usage

User-defined Functions
n Usage
Advanced User–Defined Functions
n Usage
n ResultList, Container Object, GlobalContainer Object, MappingTrace
Object
Message Mapping “Patterns”
n Summarization
n Duplicating Subtrees
n Table/Value Lookup (within source, not external)
n Tree–Reversal
Multi–Mappings
Mapping Templates
Summary

 SAP AG 2003, Title of Presentation, Speaker Name / 76

 Multi–Mappings

Multi–Mapping can only be used in ccBPM:

n n:1 Transformation
Bundles multiple messages into one message, for example, individual
purchase order items into one purchase order.
n 1:n Transformation
Splits a message into multiple messages, for example, a purchase order into
the individual purchase order items.
n n:m Transformation
Converts a message into another message, for example, a message that is
defined by interface A is converted to message that is defined by interface B.

Multi–Mappings reference multiple message structures:

n All source message structures are combined into 1 source structure.
n All target message structures are combined into 1 target structure.
n Therefore, there is only one source structure mapped to one target.

 SAP AG 2003, Title of Presentation, Speaker Name / 77

 Mapping “Patterns” – Multi–Mappings
The Message Types are entered using the Messages tab in the mapping editor.
n The root element is always <Messages>.
n The Mapping Editor inserts an element <MessageN> for each source or target message, where
N is the position of the message.

Example: Message Type (Source) Message Type (Target)

OrderHeader(1) Order(1)
OrderItem(0…unbounded) OrderInfo(1)

 SAP AG 2003, Title of Presentation, Speaker Name / 78

 Mapping “Patterns” – Multi–Mappings

Insert more Change

messages Occurrences

No msg
type
name

Mapping rules are the same as for previously discussed Message Mappings.
 SAP AG 2003, Title of Presentation, Speaker Name / 79
 Agenda
Concepts / Overview
Test/Debugging Environment
Standard Functions
n Function Usage
n Simple Function Examples
n Node Function Examples

Introduction to Most–Common Java Usage

User-defined Functions
n Usage
Advanced User–Defined Functions
n Usage
n ResultList, Container Object, GlobalContainer Object, MappingTrace
Object
Message Mapping “Patterns”
n Summarization
n Duplicating Subtrees
n Table/Value Lookup (within source, not external)
n Tree–Reversal
Multi–Mappings
Mapping Templates
Summary

 SAP AG 2003, Title of Presentation, Speaker Name / 80

 Mapping Templates

Message Mappings can be saved as Mapping Templates.

Mapping Templates can be reused (or loaded) in other Message

Mappings or Mapping Templates.

Features:

Mapping Templates can be defined for structure mappings of the

following structures:
n Data Types
n Complex types in IDocs and RFCs
n Complex types in External Definitions
n The referenced types used in mapping templates can be located in
any software component versions.

 SAP AG 2003, Title of Presentation, Speaker Name / 81

 Mapping Templates

The Mapping Editor is used to create and load the structures used by
the Mapping Templates.
Defining Mapping Templates
n The Mapping Template can be saved by:
1. Selecting the Source and Target source in the Mapping Editor
2. Choose Save Mapping Template from either the target structure context menu or
from the object toolbar
3. Enter a unique name for the new Mapping Template.

 SAP AG 2003, Title of Presentation, Speaker Name / 82

 Mapping Templates

Using Mapping Templates:

Mapping Templates can be used in Message Mappings from any software
component version:
1. In the Mapping Editor, select a type element in the source and target structure.
2. Choose Load Mapping Templates from either the target structure context menu or from
the object toolbar.
3. If mapping templates are available for the types in the source and target fields, a select
dialog window will be displayed.

The Types must

match what were
defined in the
existing Mapping
Templates.

 SAP AG 2003, Title of Presentation, Speaker Name / 83

 Agenda
Concepts / Overview
Test/Debugging Environment
Standard Functions
n Function Usage
n Simple Function Examples
n Node Function Examples

Introduction to Most–Common Java Usage

User-defined Functions
n Usage
Advanced User–Defined Functions
n Usage
n ResultList, Container Object, GlobalContainer Object, MappingTrace
Object
Message Mapping “Patterns”
n Summarization
n Duplicating Subtrees
n Table/Value Lookup (within source, not external)
n Tree–Reversal
Multi–Mappings
Mapping Templates
Summary

 SAP AG 2003, Title of Presentation, Speaker Name / 84

 Further Information

è Public Web:
http://help.sap.com
http://sdn.sap.com
http://service.sap.com
SAP Customer Services Network: http://www.sap.com/services/

è Related XI 3.0 Workshop / Training Opportunities

NetWeaver04 Overview
XI 3.0 Implementation Workshop
Introduction to XML and Technical Standards
Advanced Integration Builder
Advanced BPM
Adapter Framework
B2B and Industry Standards
Proxy Development and Deployment

 SAP AG 2003, Title of Presentation, Speaker Name / 85

 Questions?

Q&A

 SAP AG 2003, Title of Presentation, Speaker Name / 86

 Copyright 2004 SAP AG. All Rights Reserved

n No part of this publication may be reproduced or transmitted in any form or for any purpose without the express
permission of SAP AG. The information contained herein may be changed without prior notice.
n Some software products marketed by SAP AG and its distributors contain proprietary software components of other
software vendors.
n Microsoft®, WINDOWS®, NT®, EXCEL®, Word®, PowerPoint® and SQL Server® are registered trademarks of
Microsoft Corporation.
n IBM®, DB2®, DB2 Universal Database, OS/2®, Parallel Sysplex®, MVS/ESA, AIX®, S/390®, AS/400®, OS/390®,
OS/400®, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere®, Netfinity®, Tivoli®,
Informix and Informix® Dynamic ServerTM are trademarks of IBM Corporation in USA and/or other countries.
n ORACLE® is a registered trademark of ORACLE Corporation.

n UNIX®, X/Open®, OSF/1®, and Motif® are registered trademarks of the Open Group.

n Citrix®, the Citrix logo, ICA®, Program Neighborhood®, MetaFrame®, WinFrame®, VideoFrame®, MultiWin® and
other Citrix product names referenced herein are trademarks of Citrix Systems, Inc.
n HTML, DHTML, XML, XHTML are trademarks or registered trademarks of W3C®, World Wide Web Consortium,
Massachusetts Institute of Technology.
n JAVA® is a registered trademark of Sun Microsystems, Inc.

n JAVASCRIPT® is a registered trademark of Sun Microsystems, Inc., used under license for technology invented
and implemented by Netscape.
n MarketSet and Enterprise Buyer are jointly owned trademarks of SAP AG and Commerce One.

n SAP, SAP Logo, R/2, R/3, mySAP, mySAP.com and other SAP products and services mentioned herein as well as
their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other
countries all over the world. All other product and service names mentioned are trademarks of their respective
companies.

 SAP AG 2003, Title of Presentation, Speaker Name / 87

 Copyright 2004 SAP AG. Alle Rechte vorbehalten

n Weitergabe und Vervielfältigung dieser Publikation oder von Teilen daraus sind, zu welchem Zweck und in welcher
Form auch immer, ohne die ausdrückliche schriftliche Genehmigung durch SAP AG nicht gestattet. In dieser
Publikation enthaltene Informationen können ohne vorherige Ankündigung geändert werden.
n Die von SAP AG oder deren Vertriebsfirmen angebotenen Softwareprodukte können Softwarekomponenten auch
anderer Softwarehersteller enthalten.
n Microsoft®, WINDOWS®, NT®, EXCEL®, Word®, PowerPoint® und SQL Server® sind eingetragene Marken der
Microsoft Corporation.
n IBM®, DB2®, DB2 Universal Database, OS/2®, Parallel Sysplex®, MVS/ESA, AIX®, S/390®, AS/400®, OS/390®,
OS/400®, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere®, Netfinity®, Tivoli®,
Informix und Informix® Dynamic ServerTM sind Marken der IBM Corporation in den USA und/oder anderen
Ländern.
n ORACLE® ist eine eingetragene Marke der ORACLE Corporation.

n UNIX®, X/Open®, OSF/1® und Motif® sind eingetragene Marken der Open Group.

n Citrix®, das Citrix-Logo, ICA®, Program Neighborhood®, MetaFrame®, WinFrame®, VideoFrame®, MultiWin® und
andere hier erwähnte Namen von Citrix-Produkten sind Marken von Citrix Systems, Inc.
n HTML, DHTML, XML, XHTML sind Marken oder eingetragene Marken des W3C®, World Wide Web Consortium,
Massachusetts Institute of Technology.
n JAVA® ist eine eingetragene Marke der Sun Microsystems, Inc.

n JAVASCRIPT® ist eine eingetragene Marke der Sun Microsystems, Inc., verwendet unter der Lizenz der von
Netscape entwickelten und implementierten Technologie.
n MarketSet und Enterprise Buyer sind gemeinsame Marken von SAP AG und Commerce One.

n SAP, SAP Logo, R/2, R/3, mySAP, mySAP.com und weitere im Text erwähnte SAP-Produkte und -Dienst-
leistungen sowie die entsprechenden Logos sind Marken oder eingetragene Marken der SAP AG in Deutschland
und anderen Ländern weltweit. Alle anderen Namen von Produkten und Dienstleistungen sind Marken der
jeweiligen Firmen.

 SAP AG 2003, Title of Presentation, Speaker Name / 88