BIT460

PI Message Mapping
SAP NetWeaver Process Integration

Date
Training Center
Instructors

Education Website

Participant Handbook
Course Version: 95
Course Duration: 2 Day(s)
Material Number: 50102743

An SAP course - use it to learn, reference it for work

Copyright

Copyright © 2011 SAP AG. All rights reserved.

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.

Some software products marketed by SAP AG and its distributors contain proprietary software
components of other software vendors.

Trademarks

• Microsoft®, WINDOWS®, NT®, EXCEL®, Word®, PowerPoint® and SQL Server® are
registered trademarks of Microsoft Corporation.
• IBM®, DB2®, OS/2®, DB2/6000®, Parallel Sysplex®, MVS/ESA®, RS/6000®, AIX®,
S/390®, AS/400®, OS/390®, and OS/400® are registered trademarks of IBM Corporation.
• ORACLE® is a registered trademark of ORACLE Corporation.
• INFORMIX®-OnLine for SAP and INFORMIX® Dynamic ServerTM are registered
trademarks of Informix Software Incorporated.
• UNIX®, X/Open®, OSF/1®, and Motif® are registered trademarks of the Open Group.
• Citrix®, the Citrix logo, ICA®, Program Neighborhood®, MetaFrame®, WinFrame®,
VideoFrame®, MultiWin® and other Citrix product names referenced herein are trademarks
of Citrix Systems, Inc.
• HTML, DHTML, XML, XHTML are trademarks or registered trademarks of W3C®, World
Wide Web Consortium, Massachusetts Institute of Technology.
• JAVA® is a registered trademark of Sun Microsystems, Inc.
• JAVASCRIPT® is a registered trademark of Sun Microsystems, Inc., used under license for
technology invented and implemented by Netscape.
• SAP, SAP Logo, R/2, RIVA, R/3, SAP ArchiveLink, SAP Business Workflow, WebFlow, SAP
EarlyWatch, BAPI, SAPPHIRE, Management Cockpit, mySAP.com Logo and mySAP.com
are trademarks or registered trademarks of SAP AG in Germany and in several other countries
all over the world. All other products mentioned are trademarks or registered trademarks of
their respective companies.

Disclaimer

THESE MATERIALS ARE PROVIDED BY SAP ON AN "AS IS" BASIS, AND SAP EXPRESSLY
DISCLAIMS ANY AND ALL WARRANTIES, EXPRESS OR APPLIED, INCLUDING
WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE, WITH RESPECT TO THESE MATERIALS AND THE SERVICE,
INFORMATION, TEXT, GRAPHICS, LINKS, OR ANY OTHER MATERIALS AND PRODUCTS
CONTAINED HEREIN. IN NO EVENT SHALL SAP BE LIABLE FOR ANY DIRECT,
INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES OF ANY
KIND WHATSOEVER, INCLUDING WITHOUT LIMITATION LOST REVENUES OR LOST
PROFITS, WHICH MAY RESULT FROM THE USE OF THESE MATERIALS OR INCLUDED
SOFTWARE COMPONENTS.

g2011421568
 About This Handbook
This handbook is intended to complement the instructor-led presentation of this
course, and serve as a source of reference. It is not suitable for self-study.

Typographic Conventions
American English is the standard used in this handbook. The following
typographic conventions are also used.

Type Style Description

Example text Words or characters that appear on the screen. These

include field names, screen titles, pushbuttons as well
as menu names, paths, and options.
Also used for cross-references to other documentation
both internal and external.

Example text Emphasized words or phrases in body text, titles of

graphics, and tables

EXAMPLE TEXT Names of elements in the system. These include

report names, program names, transaction codes, table
names, and individual key words of a programming
language, when surrounded by body text, for example
SELECT and INCLUDE.

Example text Screen output. This includes file and directory names
and their paths, messages, names of variables and
parameters, and passages of the source text of a
program.

Example text Exact user entry. These are words and characters that
you enter in the system exactly as they appear in the
documentation.

<Example text> Variable user entry. Pointed brackets indicate that you
replace these words and characters with appropriate
entries.

2011 © 2011 SAP AG. All rights reserved. iii

About This Handbook BIT460

Icons in Body Text

The following icons are used in this handbook.

Icon Meaning

For more information, tips, or background

Note or further explanation of previous point

Exception or caution

Procedures

Indicates that the item is displayed in the instructor's

presentation.

iv © 2011 SAP AG. All rights reserved. 2011

 Contents
Course Overview ......................................................... vii
Course Goals ...........................................................vii
Course Objectives .....................................................vii

Unit 1: Creating an Operations Mapping ............................. 1

Creating an Operation Mapping.......................................2

Unit 2: Mapping Messages ............................................ 17

Creating a Message Mapping ....................................... 18
Testing a Message Mapping......................................... 32
Using Message-Mapping Functions ................................ 50

Unit 3: Advanced Mapping Concepts ............................... 65

Using Contexts in Message Mapping .............................. 66
Working with User-Defined Functions.............................. 88

Unit 4: Advanced Functions.......................................... 135

Using Parameters in Mapping Programs .........................136
Working with Value Mapping functions............................147
Mapping Multiple Messages ........................................173
Creating a Message-Mapping Template ..........................178

Unit 5: Other Mapping Types......................................... 189

Importing and Using XSLT Mapping...............................190
Creating a Java Mapping ...........................................200

2011 © 2011 SAP AG. All rights reserved. v

Contents BIT460

vi © 2011 SAP AG. All rights reserved. 2011

 Course Overview
Target Audience
This course is intended for the following audiences:

• Consultants and developers who configure scenarios for SAP NetWeaver

Process Integration in which mappings are required.

Course Prerequisites
Required Knowledge
• BIT400 (SAP NetWeaver Process Integration)

Recommended Knowledge
• JA100 (SAP J2SE Fundamentals)

Course Goals
This course will prepare you to:

• Create, test, and use message mappings

• Use advanced features of message mappings

Course Objectives
After completing this course, you will be able to:

• Create, test, and use message mappings

• Use advanced features of mapping types

SAP Software Component Information

The information in this course pertains to the following SAP Software Components
and releases:
• SAP NetWeaver Process Integration 7.3

2011 © 2011 SAP AG. All rights reserved. vii

Course Overview BIT460

viii © 2011 SAP AG. All rights reserved. 2011

 Unit 1
Creating an Operations Mapping

Unit Overview
This short introductory unit introduces general mapping tasks and discusses
operation mappings.

Unit Objectives
After completing this unit, you will be able to:
• Create an Operation Mapping
• Check the inbound and outbound service interfaces
• List the available mapping program types for PI

Unit Contents
Lesson: Creating an Operation Mapping .......................................2
Exercise 1: Create an Operation Mapping .................................9

2011 © 2011 SAP AG. All rights reserved. 1

Unit 1: Creating an Operations Mapping BIT460

Lesson: Creating an Operation Mapping

Lesson Overview
This lesson shows you how to create an operation mapping to connect operations
from service interfaces with one another. The lesson also introduces general
mapping tasks, and provides an overview of mapping program types.

Lesson Objectives
After completing this lesson, you will be able to:
• Create an Operation Mapping
• Check the inbound and outbound service interfaces
• List the available mapping program types for PI

Business Example
You are responsible for creating Operation Mappings and need to understand
the types of mapping programs that can be used in an Operation Mapping in SAP
NetWeaver Process Integration (PI).

About PI Mapping
SAP NetWeaver Process Integration mediates the message transfer between sender
and receiver systems, and in most cases these systems use different interfaces.
Thus, PI has to perform a mapping between the outbound interface of the sender
and the inbound interface of the receiver interface (or interfaces). Concepts to be
applied in mapping are:
• Structure mapping
You must define mapping rules to assign fields that are semantically identical.
• Value mapping
You must define conversion rules to transfer the field content to the target
format.
The figure Concepts Implemented in Mapping details both of these concepts.
Firstly, the source message and the target message each have their own individual
structures. These differing structures require a structure mapping. Secondly, the
value business of the source field class has to be transformed into the value 2 in
the Class target field, using a value mapping.

2 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating an Operation Mapping

Figure 1: Concepts Implemented in Mapping

The mapping tasks are implemented by mapping programs referenced in

Enterprise Services Repository.

Operation Mapping
You use an operation mapping to relate an operation of an outbound service
interface with an operation of an inbound service interface. Operation mapping is
configured to reference mapping programs, which mediate between the different
message types of two operations (from service interfaces), as illustrated in the
following figure. Various mapping programs can be used as required to mediate
between the output, input, and fault message types.

2011 © 2011 SAP AG. All rights reserved. 3

Unit 1: Creating an Operations Mapping BIT460

Figure 2: Mapping Programs Between Two Operations and Their

Corresponding Message Types

In asynchronous cases, communication is based on just one message, so mapping

is only required for the request. In synchronous cases, communication comprises
a request, a response, and, where applicable, a fault message; you can therefore
assign mapping programs in up to three different areas.
The high-level process of developing an Operation Mapping is as follows:
1. Create an Operation Mapping in the Enterprise Services Builder.
2. Assign sender and receiver Service Interfaces to the Operation Mapping.
3. Select mapping programs for request (& response) message, save, and
activate the object.
4. Reference the Operation Mapping in an Interface Determination in the
Integration Directory

Mapping-Program Types
The figure Mapping Objects provides an overview of the mapping program
types in Enterprise Services Repository, and the use of operation mappings in the
Integration Directory.

4 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating an Operation Mapping

Figure 3: Mapping Objects

Mapping programs used to map message types can be realized in the following
different ways:
• Message mapping
You create a Message Mapping graphically using the mapping editor in the
Enterprise Services Builder.
• Java mapping class
You create a Java Mapping Class in a Java IDE, and import it into Enterprise
Services Repository
• XSL transformation
You create an XSL transformation “externally” and import it into Enterprise
Services Repository.
• ABAP-XSL transformation
You create an ABAP-XSL transformation on the Integration Server (in the
ABAP stack) and reference it from within an operation mapping.
• ABAP mapping class
You create an ABAP mapping class on the Integration Server (in the ABAP
stack) and reference it from within an operation mapping.

2011 © 2011 SAP AG. All rights reserved. 5

Unit 1: Creating an Operations Mapping BIT460

The mapping editor is of particular interest in this course. It is a graphical object

editor that is used to create and test mapping programs before they are used in
collaborative processes. Mapping programs developed with the mapping editor
are called message mappings, although the other types of mapping programs do
map messages as well.

Combining Different Mapping Types

Mapping programs can access other mapping programs and make use of their
functions. This enables modularization and a reuse of existing developments.
The only limitation is that the mapping programs must be in the same software
component version or a basis software component version. See the following
overview on mapping combinations:

• Java classes in archives can be used in user-defined functions.

• Java classes can use the methods of other Java classes.
• XSLT mapping programs can insert or even import other XSLT mapping
programs.
• Java methods can be called within XSLT mapping programs.
We recommend that you save Java classes and XSLT files in separate archives.
Doing so can increase the rate of processing.

Multiple Mapping Programs in One Operation Mapping

In an operation mapping, you have the option of using multiple mapping programs
in succession and not just one, single program . However, when using multiple
mapping programs in an operation mapping, note the following important
restrictions:

• The first mapping program must have the appropriate source message.
• The output of each mapping program must match the input of the subsequent
mapping program.
• The last mapping program must have the appropriate target message.
• Identical or different mapping types are possible.
• The sequence in which mapping programs are to be executed is specified.

Hint: Not every mapping has to have the same source and target messages.

When you use the F4 help to select message mappings, you must not use any
search criteria for the source and target messages. Otherwise only those message
mappings that exactly match the expected source and target messages will be
displayed.

6 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating an Operation Mapping

Using operation mapping in configuration

You reference an operation mapping during configuration time in the Integration
Directory. It can be referenced in the following configuration objects:
• in an Interface Determination
(for message processing by the Integration Engine)
• in an Enhanced Receiver Determination
(for message processing by the Integration Engine)
• in an Integrated Configuration
(for message processing by the Advanced Adapter Engine)

Hint: If you switch from one mapping program to another within

an operation mapping, you do not need to make any changes in the
configuration.

Enhanced receiver determination

Enhanced receiver determination enables you to determine the receiver
dynamically by using an operation mapping. In this case, an interface called
ReceiverDetermination must be used as the receiver interface in the operation
mapping. At runtime, the mapping is executed in the Receiver Determination
step, independently of the mapping that later maps the sender interface to the
receiver interface.

Hint: The ReceiverDetermination service interface is in the Enterprise

Services Builder in the SAP BASIS 7.30 software component (in the
http://sap.com/xi/XI/System namespace).

2011 © 2011 SAP AG. All rights reserved. 7

Unit 1: Creating an Operations Mapping BIT460

Figure 4: Principle of Enhanced Receiver Determination

Hint: You cannot use the Enhanced Receiver Determination on the AEX
(Advanced Adapter Engine Extended) because the AEX is configured
with an Integrated Configuration, which does not support Enhanced
Receiver Determination.

8 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating an Operation Mapping

Exercise 1: Create an Operation Mapping

Exercise Objectives
After completing this exercise, you will be able to:
• Check service interfaces and create operation mappings

Business Example
Part of your daily responsibilities requires that you create and manage operation
mappings.

Task 1: Check the Outbound Service Interface

For the service interface CustomerInformation_Request in software
component version (SWCV) SC_BIT_MAP, 1.0 in namespace
http://educationsap.com/pi/mapping##: check which category the interface
belongs to, which operations exist, and whether all the referenced objects exist.
1. Check the attributes of the service interface
2. Open the referenced objects and check the namespaces.

Task 2: Check the Inbound Service Interface

Check the CustomerInformation_Provide service interface in software
component version (SWCV) SC_BIT_BASE_COMP, 1.0 in the namespace
urn:educationsap.com:bit:mapping to see whether all required objects exist.
1. Check the attributes of the service interface.
2. Open the referenced objects and check the namespaces.

Task 3: Create an Operation Mapping

Create an operation mapping OM_CustomerInfoMap to map the service
interfaces CustomerInformation_Request and CustomerInformation_Provide
to each other.
1. Create the operation mapping.
Create the OM_CustomerInfoMap operation mapping for
software component version SC_BIT_MAP 1.0 in your
namespace http://educationsap.com/pi/mapping## to map the
CustomerInformation_Request and CustomerInformation_Provide
service interfaces to each other.

2011 © 2011 SAP AG. All rights reserved. 9

Unit 1: Creating an Operations Mapping BIT460

Solution 1: Create an Operation Mapping

Task 1: Check the Outbound Service Interface
For the service interface CustomerInformation_Request in software
component version (SWCV) SC_BIT_MAP, 1.0 in namespace
http://educationsap.com/pi/mapping##: check which category the interface
belongs to, which operations exist, and whether all the referenced objects exist.
1. Check the attributes of the service interface
a) Display the service interface.
Open software component version SC_BIT_MAP, 1.0, open the
namespace http://educationsap.com/pi/mapping## and the node Service
Interfaces. Then open the object CustomerInformation_Request
by double-clicking.
b) Check the interface category.
On the Definition tab page, you can see that this is a service interface of
category outbound.
c) Confirm the interface operation mode.
In section Operations, you see one operation named
CustomerInformation_Request with mode synchronous.

Note: A service interface of interface pattern “Stateless

(XI30-Compatible)” can only have one operation, which name
has to be the service interface name.

2. Open the referenced objects and check the namespaces.

a) Check which message types are referenced.
Check that the correct message types are referenced by checking the
namespaces and also by navigating to the referenced message types and
then to the data types by double-clicking.
b) Check the namespace assigned to the data types.
A message type has an XML Namespace field that can be used
to enter a namespace for the data types used by the message
types. Check this field in particular to see whether the namespace
http://educationsap.com/pi/mapping## is also used here.
c) Check message types exist.
You can also start a check in the service interface by choosing Service
Interface → Check (F7). If a message type has been entered that does
not exist, an error message is displayed.
Continued on next page

10 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating an Operation Mapping

Task 2: Check the Inbound Service Interface

Check the CustomerInformation_Provide service interface in software
component version (SWCV) SC_BIT_BASE_COMP, 1.0 in the namespace
urn:educationsap.com:bit:mapping to see whether all required objects exist.
1. Check the attributes of the service interface.
a) Display the basis objects.
You can either open the SWCV SC_BIT_BASE_COMP, 1.0, or
navigate to the objects by expanding the node Basis Objects in the
SWCV SC_BIT_MAP, 1.0.
b) Display the selected objects.
Choose Service Interfaces in the namespace urn:education-
sap.com:bit:mapping and then open the object CustomerInforma-
tion_Provide by double-clicking.
c) Check the operation category.
On the Definition tab page, you can see that it has category inbound.
The section Operations shows one synchronous operation.
2. Open the referenced objects and check the namespaces.
a) Check which message types are referenced.
Check that the correct message types are referenced by checking the
namespaces and also by navigating to the referenced message types and
then to the data types by double-clicking.
b) Check the namespace assigned to the data types.
There is an XML Namespace field that can be used to record
a namespace for the data types used by the message types.
Check this field in particular to see whether the namespace
urn:educationsap.com:bit:mapping is also used here.
c) Check message types exist.
You can trigger a check in the service interface by choosing Service
Interface → Check (F7). If a message type has been entered that does
not exist, an error message is displayed.

Task 3: Create an Operation Mapping

Create an operation mapping OM_CustomerInfoMap to map the service
interfaces CustomerInformation_Request and CustomerInformation_Provide
to each other.
1. Create the operation mapping.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 11

Unit 1: Creating an Operations Mapping BIT460

Create the OM_CustomerInfoMap operation mapping for

software component version SC_BIT_MAP 1.0 in your
namespace http://educationsap.com/pi/mapping## to map the
CustomerInformation_Request and CustomerInformation_Provide
service interfaces to each other.
a) Create a new operation mapping.
1. Display the objects for your namespace http://education-
sap.com/pi/mapping##. To create a new operation mapping,
choose New in the context menu.
2. In the Create Object dialog box, expand the section Mapping
Objects on the left-hand, and choose Operation Mapping
3. Enter the name OM_CustomerInfoMap and choose Create.
4. Save the new operation mapping.
b) Specify the outbound and inbound interfaces.
1. Enter the outbound interface CustomerInformation_Request
and the inbound interface CustomerInformation_Provide by
using the input help. Alternatively, you can drag the interfaces to
the relevant fields by using drag and drop.

Caution: When using drag and drop, remember to

enter a value in the fields for Namespace and Software
Component Version.

2. To display detailed information at the bottom of the screen, in

particular the three tab pages Request, Response, and Fault,
choose Read Operations.

Caution: Ensure that the tab Fault is listed. If the Fault

tab is not listed, this may lead to errors later, even though
no fault message is defined in our interfaces. Choose
Read Operations to list tabs.

c) Save the operation mapping.

Note: It is not yet possible to activate the operation mapping.

d) Display the available mapping programs.

You can see which types of mapping programs can be used here,
by using the input help for the Type field (located under Mapping
Programs for request):
• Message Mapping
• Java Class

Continued on next page

12 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating an Operation Mapping

• XSL
• ABAP Class
• ABAP XSL

Hint: The operation mapping is just created to enable you to

see the selection process. You create the message mapping at
a later stage and reference it in the operation mapping. When
you have done all this, you can activate the operation mapping.

2011 © 2011 SAP AG. All rights reserved. 13

Unit 1: Creating an Operations Mapping BIT460

Lesson Summary
You should now be able to:
• Create an Operation Mapping
• Check the inbound and outbound service interfaces
• List the available mapping program types for PI

14 © 2011 SAP AG. All rights reserved. 2011

BIT460 Unit Summary

Unit Summary
You should now be able to:
• Create an Operation Mapping
• Check the inbound and outbound service interfaces
• List the available mapping program types for PI

2011 © 2011 SAP AG. All rights reserved. 15

Unit Summary BIT460

16 © 2011 SAP AG. All rights reserved. 2011

 Unit 2
Mapping Messages

Unit Overview
Introduction to message mapping.

Unit Objectives
After completing this unit, you will be able to:

• Create a message mapping

• Use the mapping editor and explain how it works
• Test a message mapping
• Use trace information to help debug issues that arise during the testing
process
• Create and test a configuration scenario
• Implement standard functions in your own message mappings
• Create and implement user-defined functions in message mappings

Unit Contents
Lesson: Creating a Message Mapping........................................ 18
Exercise 2: Create a Message Mapping ................................. 27
Lesson: Testing a Message Mapping ......................................... 32
Exercise 3: Test a Message Mapping..................................... 39
Exercise 4: Create the Configuration ..................................... 41
Lesson: Using Message-Mapping Functions................................. 50
Exercise 5: Use Standard Message-Mapping Functions............... 57

2011 © 2011 SAP AG. All rights reserved. 17

Unit 2: Mapping Messages BIT460

Lesson: Creating a Message Mapping

Lesson Overview
This lesson introduces the basic concepts of the mapping editor and shows you
how to use the mapping editor to create a message mapping.

Lesson Objectives
After completing this lesson, you will be able to:
• Create a message mapping
• Use the mapping editor and explain how it works

Business Example
You are responsible for the development of mappings in SAP NetWeaver Process
Integration and must be able to create, modify, and manage mappings that are
developed. For this reason, you need to know:
• How the mapping editor works
• How to modify the message-mapping structure
• How to make use of variables and advanced functions in the mapping editor

The Mapping Editor

The Enterprise Services Builder has an integrated mapping editor that you can
use to graphically represent and manage mappings. Since this involves mappings
between messages, we refer to this procedure as message mapping. In Enterprise
Services Repository, Java programs are generated from message mappings. These
Java programs are compiled for the runtime and packed into JAR files. The
process occurs automatically and does not have to be triggered by the user, or
monitored in any way.
Graphical mapping tools provide an easy-to-use method of defining connections
between source and target structures and values, in addition to the integrated
functions that you can use. To help overcome problems when dealing with
complex messages you can add your own user-defined functions to the existing
standard functions.

18 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Message Mapping

Graphical mapping is one method of defining a mapping in PI. However, there

are others. Users with the appropriate knowledge and experience with mapping
can sometimes find it helpful to use an alternative mapping type, such as: Java,
ABAP, or XSLT mapping. These alternative mapping programs are summarized
in the following list:

• Java Programs generated from message mappings:

– Enhanced with integrated standard functions
– Enhanced with user-defined Java functions
• Java programs imported as JAR or Zip archives
• XSLT files imported as JAR or Zip archives:
– Enhanced with integrated standard functions
– Enhanced with user-defined Java functions
• ABAP classes and XSLT programmed on the PI ABAP stack
As an alternative to the mapping programs generated by the mapping editor,
you can specify Java programs or XSLT files as imported archives directly in
the operation mapping as mapping programs. If required, you can also use
the integrated and user-defined functions (listed above) in XSLT files. ABAP
mappings are developed in the ABAP Workbench and are not imported into
Enterprise Services Repository since during runtime, these mapping programs are
executed directly in the ABAP Workbench of the PI ABAP Stack.

The Message-Mapping Structure

All mappings are based on the principle that the fields of a target structure are
assigned to fields in a source structure; a field can be either an element or an
attribute from the relevant XML document. An assignment can comprise a
complex combination of functions, which are needed, for example, for calculations
or format conversions. To ensure order and clarity, you can split the mapping into
sub mappings for each assignment; each sub mapping is displayed in the mapping
editor in a separate area.
The figure Structure Overview and the Data-Flow Editor illustrates the two
overviews provided by the mapping editor:
• Structure:
The structure overview displays the structures of the selected source and
target documents. You can extend the structure overview to include a
representation of assignments between elements in the documents.
• Data-flow:
The data flow editor displays the sub mapping for the target field selected in
the structure overview.

2011 © 2011 SAP AG. All rights reserved. 19

Unit 2: Mapping Messages BIT460

Figure 5: Structure Overview and the Data-Flow Editor

Source and Target Structures

Various methods are available for generating the source and target structures that
are imported into the mapping editor. For example, you can use any message
types generated in Enterprise Services Repository, where the underlying structure
of the message type is stored in XSD.
The mapping editor also supports the use of imported external definitions; the
import process automatically extracts the structure of XML files. As a general rule,
any XSD files created with the data type editor can be imported. However, some
tags from XSD files are ignored. For example, the tags <xsd:include> and
<xsd:import> are not supported.
The mapping editor supports the import of the following message-type structures,
files, and definitions:

• From Enterprise Services Repository:

– Message types developed in Enterprise Services Repository
– Imported external definitions (WSDL, XSD, or DTD files)
– Imported SAP metadata (RFC or IDoc)
• From the local file system (XSD or XML files):
– Not all XSD tags are supported (all XSD tags generated using the
data type editor can be imported)
– <xsd:include> and <xsd:import> are not supported

20 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Message Mapping

Data Flow Configuration

The mapping editor includes a data flow editor, which you can use to map fields
in the source message structure to the appropriate fields in the target message
structure. You can use the following methods for assigning target fields to the
corresponding source fields:
• Field-assignment Method 1:
Transfer the target field to the data flow editor by double-clicking or by
using drag and drop. Source fields can be transferred in the data flow editor
in the same way. If a mapping already exists for the selected target field,
this is shown in the data flow editor, and allows you, for example, to create
additional mappings for further source fields. You assign fields by simply
drawing lines between the source and target fields.
• Field-assignment Method 2:
Connect the target and source elements using drag and drop. This
automatically creates the assignment link between the fields.
Figure Connecting Source and Target Fields illustrates the field-assignment
methods outlined above.

Figure 6: Connecting Source and Target Fields

Hint: PI also allows you to define target-field mappings for multiple

target fields simultaneously.

2011 © 2011 SAP AG. All rights reserved. 21

Unit 2: Mapping Messages BIT460

The data flow editor can contain multiple target fields with identical (or at least
similar) target-field mappings. This feature not only simplifies the mapping
procedure, it also enables you to execute complex functions once and assign the
resulting value to multiple target fields. For performance reasons, we highly
recommend that you use this feature.

Figure 7: Data-Flow Editor: Target-Field Mapping for Multiple Target Fields

Simultaneously

Message-Mapping Field Variables

PI enables the use of variables in the target structure. Before defining target-field
mappings, you can use variables to calculate a value that can be reused in
several target-field mappings for one block. If several target fields have identical
mappings, less time is required to define them; you define the target-field mapping
once for one variable and then assign this variable to all other target fields.
In the following example, a date must be formulated comprising a month, day, and
year. This date then has to be mapped to the Date and TimeStamp target fields.
The variable DateVar simplifies these two target-field mappings:

22 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Message Mapping

Figure 8: How Graphical Variables Are Used (Example)

Hint: To create a variable, use the context menu for a field in the target
structure that possesses additional subelements and choose Add Variable.
The mapping editor inserts the variable as the first subnode of the field.
This variable is visible for all nodes at the same hierarchy level and all
subnodes.

You can use the Var variable as a target field, too, or define a target-field mapping
for Var in the data flow editor. In the target-field mapping, you can also use values
from variables that appear before Var in the structure flow.
To use a variable as a source field in a target-field mapping, drag the variable
to the data flow editor.

Advanced Message-Mapping Functions

The application toolbar in the mapping editor displays icons you can use to start
functions that make it easier to create mappings. The following table lists and
explains some of the more commonly used functions.

2011 © 2011 SAP AG. All rights reserved. 23

Unit 2: Mapping Messages BIT460

Icon Function Description

Preview the mapping in pure text Preview the target-field mapping
format. in pure text format in the data
flow editor.
Activate the mass-assignment Before you start a mass
option. assignment operation, you
must select both nodes in the
source and target structures.
Mass assignment ensures that any
fields with the same names that are
located under the selected nodes
are automatically connected. The
few remaining target fields that
remain unlinked must be mapped
manually.
The mass-assignment function is
particularly useful if you need
to map larger structures, such as
IDoc data.
Display a graphical view that You can use this function for
outlines dependencies between specific target fields, for sub
source and target fields. structures, or for the whole
structure, and can simply close it
when it is no longer required.

24 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Message Mapping

Figure 9: GUI Message-Mapping Functions

2011 © 2011 SAP AG. All rights reserved. 25

Unit 2: Mapping Messages BIT460

26 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Message Mapping

Exercise 2: Create a Message Mapping

Exercise Objectives
After completing this exercise, you will be able to:
• Create message mappings in Enterprise Services Repository
• Reference message mappings in operation mappings

Business Example
You are responsible for mapping one message structure (type) to another. For this
reason, you want to create a message mapping and use it in an operation mapping.

Task 1:
Create a message mapping to map message types MtCustomerName and MtName.
1. Create the new message mapping MM_CustomerNameMerge.
In software component version SC_BIT_MAP, 1.0, in your
namespace http://educationsap.com/pi/mapping##, create the
message mapping MM_CustomerNameMerge to map the
message types MtCustomerName (SWCV SC_BIT_MAP,
1.0, namespace http://educationsap.com/pi/mapping##) and
MtName (SWCV SC_BIT_BASE_COMP, 1.0, namespace
urn:educationsap.com:bit:mapping) to one another.
Map the two fields Surname and Name from the source structure so that they
are separated by a blank in MtName.
The sequence must be: first name, then surname.

Task 2:
Reference the message mapping in the operation mapping OM_CustomerIn-
foMap.
1. Reference the message mapping MM_CustomerNameMerge in the operation
mapping OM_CustomerInfoMap.

2011 © 2011 SAP AG. All rights reserved. 27

Unit 2: Mapping Messages BIT460

Solution 2: Create a Message Mapping

Task 1:
Create a message mapping to map message types MtCustomerName and MtName.
1. Create the new message mapping MM_CustomerNameMerge.
In software component version SC_BIT_MAP, 1.0, in your
namespace http://educationsap.com/pi/mapping##, create the
message mapping MM_CustomerNameMerge to map the
message types MtCustomerName (SWCV SC_BIT_MAP,
1.0, namespace http://educationsap.com/pi/mapping##) and
MtName (SWCV SC_BIT_BASE_COMP, 1.0, namespace
urn:educationsap.com:bit:mapping) to one another.
Map the two fields Surname and Name from the source structure so that they
are separated by a blank in MtName.
The sequence must be: first name, then surname.
a) Create a new message mapping.
1. In SWCV SC_BIT_MAP, 1.0 navigate to your namespace
http://educationsap.com/pi/mapping##.
2. To create a new message mapping, choose New in the context
menu.
3. Enter the name MM_CustomerNameMerge and choose Create.
b) Select the source message type.
1. In the tree structure in your namespace http://education-
sap.com/pi/mapping## (software component SC_BIT_MAP),
navigate to the Message Types node.
2. Locate the message type MtCustomerName.
3. Drag the message type MtCustomerName to the section Enter
a source message (above the structure section) in the source
message structure.

Hint: Only the name of the message type is listed

in the graphical mapping editor display (for example,
MtCustomerName), and not the name of the referenced data
type (for example, PersonName).

Continued on next page

28 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Message Mapping

c) Select the target message type.

1. In the tree structure in your namespace urn:edu-
cationsap.com:bit:mapping (software component
SC_BIT_BASE_COMP), navigate to the Message Types node.
2. Locate the message type MtName.
3. Drag the message type MtName to the Enter a target message
section in the target message structure.
d) Display mapped fields in the data flow editor.
1. Double-click the target field MtName and the source fields
Surname and Name to display them in the data-flow editor.
2. Select the Text function and drag the concat function to the
data-flow editor.
3. Drag one connection line from the Name outbound field (on the
right-hand side) to the concat inbound field on the upper left-hand
side (since the first name should come first).
4. Drag another connection line from the Surname outbound field
(on the right-hand side) to the concat inbound field on the lower
left-hand side.
5. Drag a connection line from the concat outbound field to the
MtName inbound field.
e) Separate mapped fields with a delimiter.
1. Double-click the concat function and enter a blank as a delimiter
to separate the Name and Surname fields with a blank.
2. Choose OK to exit the screen for maintaining the properties of
the concat step.
f) Display the mapping as text.
To display the mapping as text, choose Text Preview.
/ns1:MtName=concat(/ns0:MtCustomerName/Name,
/ns0:MtCustomerName/Surname, delimeter= )

g) Save and activate the message mapping.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 29

Unit 2: Mapping Messages BIT460

Task 2:
Reference the message mapping in the operation mapping OM_CustomerIn-
foMap.
1. Reference the message mapping MM_CustomerNameMerge in the operation
mapping OM_CustomerInfoMap.
a) Display the operation mapping.
In your namespace http://educationsap.com/pi/mapping##, navigate
to the Operation Mappings node and open the operation mapping
OM_CustomerInfoMap by double-clicking it.
b) Maintain the message mapping.
Switch to change mode and use the input help on tab Request in the
section below Mapping Program to select your message mapping
MM_CustomerNameMerge.
c) Save and activate the operation mapping.

30 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Message Mapping

Lesson Summary
You should now be able to:
• Create a message mapping
• Use the mapping editor and explain how it works

2011 © 2011 SAP AG. All rights reserved. 31

Unit 2: Mapping Messages BIT460

Lesson: Testing a Message Mapping

Lesson Overview
This unit explains how message mappings function and what options you have for
testing. You will also learn how to create and test a configuration.

Lesson Objectives
After completing this lesson, you will be able to:
• Test a message mapping
• Use trace information to help debug issues that arise during the testing
process
• Create and test a configuration scenario

Business Example
You are responsible for the development of mappings in SAP NetWeaver Process
Integration and need to know how message mappings function. You also need an
overview of the tools the mapping editor provides to enable you to test message
mappings.

Testing Procedures in Message Mapping

Enterprise Services Repository generates Java programs out of message mappings,
which are compiled for the runtime and packed into JAR files. If you create a
message mapping and save it without producing errors, this merely indicates
that it can be compiled. It means that you have set all target fields that you are
required to set, and that there are no unset arguments for the functions used. Note
that, despite the apparent completeness or accuracy of your data, you may still
encounter difficulties at runtime.

32 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Testing a Message Mapping

To help you understand the reasons for unexpected mapping results or why
exceptions occur at runtime, note the following points, which explain how
message mappings are processed at runtime:
1. Source Fields:
Source fields are read into queues by the message mappings. This procedure
improves performance and enables large messages to be processed, since
the entire message does not actually have to be stored in the memory as
a tree structure.
2. Queues:
Queues are processed by the functions of the target-field mappings.
Additional functions can be allocated to the result queues if multiple
functions are called in succession.
3. Target Fields:
Values from the result queues are used to fill the target fields. As part of
the process, the values are compared to the attributes for occurrence (the
number of times a field appears in one or more hierarchy structures) in the
following way:
• Upper Occurrence Limit:
If the upper limit for the number of occurrences of a target field is
exceeded, additional result values from the result queue are ignored.
• Lower Occurrence Limit:
If the lower limit for the number of occurrences of a field is not reached,
an exception is triggered.

2011 © 2011 SAP AG. All rights reserved. 33

Unit 2: Mapping Messages BIT460

Figure 10: Processing Message Mappings

Message-Mapping Queues
A message-mapping queue consists of all the values of a field in the data flow
editor. This applies to source fields, target fields, and any fields created by
mapping steps. These queues serve as important tools for testing since you can
display them in the message mapping as soon as test data is available. This applies
not only to source fields, but to every processing step in the message mapping
process.
The message-mapping process makes use of the following queues:
• Inbound queue
Data from fields in the source message
• Processing queue
Data from inbound queues, which is being processed by the message-mapping
template
• Result queue
Data for entry in fields in the target message

Hint: You can debug the individual steps in the message-mapping process
by displaying the queue for each function in the message mapping. This is
explained in more detail in the Queues and Context lesson.

34 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Testing a Message Mapping

Trace Messages
During runtime testing, it is possible to write information about the current status
of the message-mapping process to a trace file. You can view the tracing data in
the trace area for the message in the message monitor (SOAP Header → Trace).
However, you can only view the trace data the earliest after the message mapping
successfully completes, that is, after the processing step Request Message
Mapping. You can also view the trace data when testing message mappings in
Enterprise Services Repository, assuming the trace level there is set accordingly.
You can assign trace messages any trace level, regardless of their level of
importance (priority). The following trace levels are possible:
• 1 (Information)
• 2 (Warning)
• 3 (Debug)
Pipeline processing is also specified a trace level. You can only see a trace
message in the monitor if its priority has at least the same trace level as the
pipeline processing. If the trace level of the pipeline, for example, is level 1,
debug messages, which are level 3, are not displayed.

Hint: You specify the trace level of the pipeline in the configuration for
the Integration Engine. Call transaction SXMB_ADM, choose Integration
Engine Configuration and, under Specific Configuration Data, choose
RUNTIME as the category and TRACE_LEVEL as the parameter.

Test Environment for Operation Mapping

After you have defined an operation mapping, you can check whether it functions
correctly at runtime by using the Test tab page in the mapping editor. You can test
the mapping for either the request, response, or fault message.

Caution: Make sure that the mapping programs to be tested are in

Enterprise Services Repository. You cannot test ABAP mappings. Note
that, for the generated Java source code to compile, message mappings
must be complete.

Test Environment for Message Mapping

The Test tab in the Mapping Editor structure overview provides functions that you
can use to test the accuracy of your mappings. The functions are displayed in the
application toolbar at the top of the Test tab page.
The various icons and their functions are illustrated in the figure below.

2011 © 2011 SAP AG. All rights reserved. 35

Unit 2: Mapping Messages BIT460

Figure 11: GUI Standard Functions in Test

After you load an XML file or create an empty XML structure, you can set the
values and attributes in either the graphical editor or the text-based editor. In the
graphical editor, you can use the options in the context menu to duplicate subtrees,
delete nodes, and add elements or attributes. In the text-based editor, you have
to perform each of the add, delete, and duplicate steps manually. However, the
text-based editor enables you to create test cases for PI scenarios quickly and
easily by using the copy-and-paste feature.
You can also use header parameters when testing. Header parameters are not
business fields in the payload; header parameters are meta information such as
the sender interface - parameters that are available as runtime constants in the
PI-SOAP message header at runtime.
When you start the mapping process for testing purposes, you can observe the test
results in the structure overview for the target fields.

Mapping Testing Functions

The mapping test environment provides the following functions, which are
available on the Test tab page in the structure overview.

36 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Testing a Message Mapping

Icon Test Function

Load an XML file from the local file system to define the source
values.
Create an empty source structure; you then manually enter data for
this structure.
Start the message-mapping process.
Create and open a test case
Save a test case

Delete a test case

Switch to the graphical message-mapping editor (toggle display
details )
Switch to the text-based message-mapping editor

2011 © 2011 SAP AG. All rights reserved. 37

Unit 2: Mapping Messages BIT460

38 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Testing a Message Mapping

Exercise 3: Test a Message Mapping

Exercise Objectives
After completing this exercise, you will be able to:
• Test message mappings in Enterprise Services Repository

Business Example
You want to check whether a message mapping you created functions correctly,
without having to apply it at runtime.

Task:
Test your message mapping MM_CustomerNameMerge.
1. Open your message mapping MM_CustomerNameMerge.
2. Maintain your test data and perform a test.
3. Create a test case.

2011 © 2011 SAP AG. All rights reserved. 39

Unit 2: Mapping Messages BIT460

Solution 3: Test a Message Mapping

Task:
Test your message mapping MM_CustomerNameMerge.
1. Open your message mapping MM_CustomerNameMerge.
a) In SWCV SC_BIT_MAP, 1.0, navigate to your namespace
http://educationsap.com/pi/mapping##, choose the Message Mappings
node, and open your message mapping by double-clicking it.
2. Maintain your test data and perform a test.
a) Navigate to the test interface by choosing the Test tab page (beside
Definition).
b) Enter values for the Surname and Name fields.
c) Execute the test by choosing the Start Transformation icon at the
bottom of the screen on the left.
d) Messages are displayed in the lower area. If a test if successful, the
results are displayed in the right-hand area of the window.
3. Create a test case.
a) Switch to edit mode for the message mapping.
b) Create a test case by choosing the Add Test Instance icon (top row, third
icon from the left). Name the test case TEST1_##.
c) Delete the entered values by choosing Create Instance (second icon
from left). Open your test case by choosing Open Test Case / TEST1_##
(sixth icon from left). Your saved values are now entered.

40 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Testing a Message Mapping

Exercise 4: Create the Configuration

Exercise Objectives
After completing this exercise, you will be able to:
• Create the required configuration for testing purposes

Business Example
You want to test your mapping at runtime using a configured scenario.

Task:
Configure a scenario between the sender BC_CI_Requestor_## and the
receiver Training with the interfaces CustomerInformation_Request
and CustomerInformation_Provide using your operation mapping
OM_CustomerInfoMap.
1. Create a new configuration scenario CS_BIT_CustomerInfo_##.
2. Create a new business component BC_CI_Requestor_## and add it to
your configuration scenario CS_BIT_CustomerInfo_##.
3. Maintain the sender interface for the Business Component.
Maintain the sender interface CustomerInformation_Request from your
namespace http://educationsap.com/pi/mapping## for your business
component BC_CI_Requestor_##.
4. Create a communication channel BC_CI_Req_##_HTTP_Sender for
sender BC_CI_Requestor_##.
Adapter Type shall be HTTP, Sender.
5. Create a sender agreement for sender BC_CI_Requestor_##, interface Cus-
tomerInformation_Request and channel BC_CI_Req_##_HTTP_Sender.
6. Create a receiver determination for sender BC_CI_Requestor_## and
the sender interface CustomerInformation_Request from the namespace
http://educationsap.com/pi/mapping## and maintain the business system
Training as the receiver.
7. Create an interface determination for this receiver determination.
Specify CustomerInformation_Provide as the receiver interface in the
namespace urn:educationsap.com:bit:mapping. Reference your operation
mapping OM_CustomerInfoMap as the mapping.
8. Create a receiver agreement for the parameters mentioned above, by
referencing the existing communication channel Training_Proxy_In.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 41

Unit 2: Mapping Messages BIT460

9. Save and activate all objects.

10. Test the changes.
Start the HTTP client and send a suitable request. Test the result in the HTTP
client and in the message monitor of the Integration Server.

42 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Testing a Message Mapping

Solution 4: Create the Configuration

Task:
Configure a scenario between the sender BC_CI_Requestor_## and the
receiver Training with the interfaces CustomerInformation_Request
and CustomerInformation_Provide using your operation mapping
OM_CustomerInfoMap.
1. Create a new configuration scenario CS_BIT_CustomerInfo_##.
a) Log on to the Integration Directory.
b) Create a configuration scenario.
1. Navigate to Object → New → Administration and choose
Configuration Scenario.
2. Name the scenario CS_BIT_CustomerInfo_##.
3. Enter a description for the configuration scenario (for example,
“Mapping Test”), and select No Model under Type of ES
Repository Model.
4. Create the configuration scenario: choose Create.
c) Save your configuration scenario.
2. Create a new business component BC_CI_Requestor_## and add it to
your configuration scenario CS_BIT_CustomerInfo_##.
a) Create the business component.
Navigate to Object → New → Collaboration Profile and choose
Business Component.
b) Define the business-component properties.
Leave the Party field empty, name your business component
BC_CI_Requestor_##, enter Sender as the description, and select
your scenario CS_BIT_CustomerInfo_## in the Add to Scenario field.
c) Create your business component; choose Create.
d) Save your business component.
3. Maintain the sender interface for the Business Component.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 43

Unit 2: Mapping Messages BIT460

Maintain the sender interface CustomerInformation_Request from your

namespace http://educationsap.com/pi/mapping## for your business
component BC_CI_Requestor_##.
a) Edit the sender interface.
On the detail screen for your business component BC_CI_Requestor_##
(in edit mode), navigate to the Sender tab page.
b) Select and assign the service interface.
To reference your service interface CustomerInformation_Request from
your namespace http://educationsap.com/pi/mapping## of software
component version SC_BIT_MAP (1.0), use the input help for the
Name field (located under Outbound Interfaces).
c) Save the business component.

Hint: When you assign an interface to the business component,

the assigned interface appears in the input help in the
configuration that follows.

4. Create a communication channel BC_CI_Req_##_HTTP_Sender for

sender BC_CI_Requestor_##.
Adapter Type shall be HTTP, Sender.
a) Create object: communication channel
Navigate to Object → New → Collaboration Profile and choose
Communication Channel.
b) Maintain Communication Component and Communication Channel
name.
Select Communication Component BC_CI_Requestor_##
and enter the name for the new Communication Channel as
BC_CI_Req_##_HTTP_Sender. Choose Create to create the object.
c) Select Adapter Type HTTP. Keep all other parameters to their default
value. Save the channel.

Continued on next page

44 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Testing a Message Mapping

5. Create a sender agreement for sender BC_CI_Requestor_##, interface Cus-

tomerInformation_Request and channel BC_CI_Req_##_HTTP_Sender.
a) Create a new sender agreement.
Navigate to Object → New → Collaboration Agreements and choose
Sender Agreement.
b) Specify the sender agreement properties.
Leave the Communication Party field empty, and enter
BC_CI_Requestor_## as the sender and CustomerInformation_Request
as the interface. If you use the input help for all fields, the namespace
http://educationsap.com/pi/mapping## is entered automatically.
c) Create the sender agreement: choose Create.
d) Select the communication channel.
Use the input help for Sender Communication Channel to select the
channel BC_CI_Req_##_HTTP_Sender.
e) Save the sender agreement.
6. Create a receiver determination for sender BC_CI_Requestor_## and
the sender interface CustomerInformation_Request from the namespace
http://educationsap.com/pi/mapping## and maintain the business system
Training as the receiver.
a) Create a new receiver determination.
Navigate to Object → New → Configuration Objects and choose
Receiver Determination.
b) Specify the receiver-determination properties.
Leave the Communication Party field empty, and enter
BC_CI_Requestor_## as the sender of your business component and
CustomerInformation_Request as the interface. If you use the input help
for all fields, the namespace http://educationsap.com/pi/mapping##
is entered automatically.
c) Create the receiver determination: choose Create.
d) Maintain the business system.
Under Configured Receivers, maintain business system Training as the
receiver in the Communication Component field using the input help.
e) Save the changes to your receiver determination.
7. Create an interface determination for this receiver determination.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 45

Unit 2: Mapping Messages BIT460

Specify CustomerInformation_Provide as the receiver interface in the

namespace urn:educationsap.com:bit:mapping. Reference your operation
mapping OM_CustomerInfoMap as the mapping.
a) Display the receiver determination configuration.
1. In your receiver determination, choose the Configuration
Overview tab page. Navigate to the lower area Configuration
Overview for Receiver Determination.
2. Use the small triangular icon to the left of Training (and under
Receiver) to expand the display.
b) Select the receiver determination.
Select the entry CustomerInformation_Request. A list of existing
configuration objects now appears in the Objects of Selected Connection
area on the right of the screen. The Receiver Determination line should
contain only one entry.
c) Specify a new interface determination.
In the Objects of Selected Connection area, click the interface
determination line and create a new interface determination by choosing
New Specific from the context menu. You have now predefined all the
known parameters in the interface determination.
d) Specify the receiver interface.
Use the input help for the field Operation Mapping to select your
operation mapping OM_CustomerInfoMap (SC_BIT_MAP 1.0).

Hint: The receiver interface CustomerInformation_Provide

(namespace urn:educationsap.com:bit:mapping) is derived
from the operation mapping.

e) Reference the operation mapping.

To use the input help for the operation mapping, navigate to the
Operation Mapping field. Reference your operation mapping OM_Cus-
tomerInfoMap in the namespace http://educationsap.com/pi/mapping##
(SWCV SC_BIT_MAP 1.0).
f) Save your interface determination.
Close the interface determination to return to the configuration
overview for the receiver determination.
g) Display the newly referenced interface determination.

Continued on next page

46 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Testing a Message Mapping

Refresh the display under Configuration Overview for Receiver

Determination by using the Refresh icon. Your interface determination
is now listed in the Objects of Selected Connection area.
8. Create a receiver agreement for the parameters mentioned above, by
referencing the existing communication channel Training_Proxy_In.
a) Create a receiver agreement.
In the Objects of Selected Connection area, click the receiver agreement
line and create a new receiver agreement by choosing New Specific
from the context menu. You have now predefined all the known
parameters in the receiver agreement.
b) Reference the existing communication channel.
Use the input help to reference the existing communication channel
Training_Proxy_In in the Receiver Communication Channel field of
the receiver agreement.
c) Save your receiver agreement.
Close the receiver agreement to return to the configuration overview
for the receiver determination.
d) Display the newly added receiver agreement.
Refresh the display under Configuration Overview for Receiver
Determination by using the Refresh icon. Your receiver agreement
is now listed with the name of the communication channel directly
below it.
9. Save and activate all objects.
a) Display the changed lists.
Switch to the Change Lists tab page in the Integration Builder.
b) Activate all changes.
Choose Activate from the context menu of the Standard Change List
node.
c) In the displayed list, leave all objects selected and choose Activate.
10. Test the changes.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 47

Unit 2: Mapping Messages BIT460

Start the HTTP client and send a suitable request. Test the result in the HTTP
client and in the message monitor of the Integration Server.
a) Open the HTTP client.
Open the HTTP client from the file share. Your instructor will tell you
where to find the file.
b) Start the HTTP client.
This simulates an application that generates an XML document and
then sends it to the SAP PI pipeline by using the HTTP adapter. If
necessary, correct the details for the sender service so that they match
those for your scenario configuration.
c) Transfer the document to the pipeline; choose Send.
Since this involves synchronous communication (quality of service is
BE for “Best Effort”), a response appears in the form under Result
in the last text area.
d) Check the status of the test message.
Call transaction SXI_MONITOR on the Integration Server and check
the processing of your messages in the message monitor.
e) Display trace information.
Navigate to the detail view of your message and open the trace (under
SOAP Header → Trace) in the processing step Request Message
Mapping in either one of the windows.
f) Locate the trace messages relating to message-mapping and operation
mapping.
At the bottom of the trace area, you can find the message indicating
which operation mapping and mapping program were executed:
<Trace level="1" type="T">
Operation Mapping http://educationsap.com/pi/mapping##
OM_CustomerInfoMap</Trace>
<Trace level="2" type="T">Mode 0</Trace>
<Trace level="2" type="T">
...
Call method execute of the application Java mapping
com.sap.xi.tf._MM_CustomerNameMerge_</Trace>
<Trace level="2" type="T">
Java mapping com/sap/xi/tf/_MM_CustomerNameMerge_
completed.
executeStep() of com.sap.xi.tf._MM_CustomerNameMerge_
</Trace>

48 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Testing a Message Mapping

Lesson Summary
You should now be able to:
• Test a message mapping
• Use trace information to help debug issues that arise during the testing
process
• Create and test a configuration scenario

2011 © 2011 SAP AG. All rights reserved. 49

Unit 2: Mapping Messages BIT460

Lesson: Using Message-Mapping Functions

Lesson Overview
This lesson explains how to use standard functions in message mapping
and provides examples of how some of the more common functions can be
implemented. You will also learn how to create and make use of user-defined
functions in message mapping.

Lesson Objectives
After completing this lesson, you will be able to:
• Implement standard functions in your own message mappings
• Create and implement user-defined functions in message mappings

Business Example
You are responsible for the development of mappings in SAP NetWeaver Process
Integration and require an overview of the purpose and use of standard functions
for message mapping in the mapping editor. You also need to understand how to
create user-defined functions in message mapping.

Predefined Message-Mapping Functions

A simple assignment between source fields and target fields is not always sufficient
to produce the required level of accuracy and efficiency in the message-mapping
process. The mapping editor provides a variety of standard functions for use in
the mapping of message structures. The predefined functions are organized into
different categories, for example: text strings, arithmetic calculations, (runtime)
constants, conversions, date format conversions, boolean comparisons, statistical
functions for all fields of a context, and functions for special structure mappings.

Hint: If you double-click anywhere in the background of the data flow

editor, the system displays a menu containing all the standard functions
that you can select, as well as a separate list containing the functions you
used last. You can also copy the paths of functions in the data flow editor
and use them for other target fields.

The figure Generic Standard Functions illustrates some generic examples of

standard functions. This lesson also provides further examples of the common
usages for text, date, boolean, and arithmetic functions in message mapping.

50 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Message-Mapping Functions

Figure 12: Generic Standard Functions

Note: Input values and returned output values are mandatory for all
functions except generating functions. For example, a constant function
does not require input values.

For some functions, you must set parameters. For example, the separator property
in the concat function must be defined. You can enter values for parameters by
double-clicking the function used in the data-flow editor. A function handles all
source and target fields as strings. For none string input parameters (for example,
integers), the contents of that parameter undergo a data-type conversion (casting).
If the values cannot be converted successfully, the mapping runtime triggers
a Java exception.

Text Functions in Message Mapping

The following figure outlines the standard text function concat and illustrates
how it works.

Figure 13: concat Standard Function

2011 © 2011 SAP AG. All rights reserved. 51

Unit 2: Mapping Messages BIT460

The following figure illustrates how to use the standard text function substring.
Note that parameters must be set for this function.

Hint: For the substring function, the parameters that need to be

maintained are not the parameters that are displayed, and that the index
count starts at 0.

Figure 14: substring Standard Function

Date Functions in Message Mapping

The following figure illustrates how to use the standard date function dateTrans.
Note that parameters must be set for this function.

Figure 15: dateTrans Standard Function

52 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Message-Mapping Functions

The dateTrans function has some enhanced settings. For example, in addition to
date formats, the numbering for weekdays and calendar weeks is country-specific.
You define the necessary conventions for this in the function properties.
• First Weekday
This parameter defines which day of the week is the first day of the week.
For example, in the USA it is Sunday, but in France it is Monday. The
numbering starts at 1.
• Minimum Number of Days Required in the First Week
This parameter defines how many days the first week of a year must have for
it to be counted as the first calendar week.
• Calendar Is Lenient
This checkbox enables you to control whether invalid dates trigger an
exception or not.

Boolean Functions in Message Mapping

Boolean message-mapping functions evaluate conditions that return Boolean
values. Standard functions that return Boolean values return the string true or
false. Standard functions that expect Boolean values interpret the values “1”
and “true” (not case-sensitive) as true and all other values as false.
The Boolean functions If and IfWithoutElse are illustrated in the figure Boolean
Functions. Boolean functions return the values true or false. The values 1 or
true (not case-sensitive) can be used as input values for true.

Figure 16: Boolean Functions

2011 © 2011 SAP AG. All rights reserved. 53

Unit 2: Mapping Messages BIT460

Arithmetic Functions in Message Mapping

You can only enter numerical values for the arithmetic function category (this
includes values with digits after the decimal point). If the value cannot be
interpreted as a digit, then the system triggers a Java exception. Otherwise, all
calculations are executed with the precision of the Java data type float. The format
of the result value depends on the result: If the result is a value with digits after
the decimal point, these remain unchanged. In results, any trailing zeros after
the decimal point are deleted to enable conversion back into string format. For
example, the result of the calculation 4.2 - 0.2 is 4 and not 4.0.
The figure Arithmetic Functions: FormatNum explains FormatNum, the most
important arithmetic function, and how it works. The results returned by arithmetic
operations can be converted to the required target format by using FormatNum.

Figure 17: FormatNumber arithmetic function

User-Defined Functions in Message Mapping

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
message-mapping structure, you can create your own user-defined functions. You
can create Java source text in this function, and the ES Builder saves it in a local
function library for use in the message-mapping process.

Hint:

54 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Message-Mapping Functions

To use a user-defined function in more than one message mapping or

mapping template, create the user-defined functions in function libraries
in the ES Repository.

The user-defined function is included in the Java coding that is generated for the
message mapping as a Java method. The new (user-defined) function is visible
in the data flow editor in the function category that you assigned to the function
in the function properties. You can insert user-defined functions in the data flow
editor in the same way as you insert a standard message-mapping function.

Caution: It is important to test any new user-defined function in the test

environment before releasing it for use in a wider implementation.

Message-Mapping Function Categories

The mapping editor provides a selection of standard functions to help define
message mappings. The functions are organized in the categories listed and
described in the following table:

Function Action
Category

Arithmetic Calculate or format values in message-mapping fields, for

functions: example: add, subtract, greater, or FormatNum

Boolean Implement conditions in your mappings, for example: If

functions: and IfWithoutElse. All functions in this category expect
Boolean input values.

Constant Generate a value for a target field rather than take the value
functions: from a source field, for example: Constant and CopyValue.

Conversion Execute a value mapping using a fixed or assigned value

functions: table, for example: FixValues and Valuemapping.

Date Define the date format for the source or target

functions: message-mapping structure, for example: dateTrans
(convert date format) and CompareDate. The format
adheres to the convention as defined in the standard Java
class java.util.SimpleDateFormat.

2011 © 2011 SAP AG. All rights reserved. 55

Unit 2: Mapping Messages BIT460

Function Action
Category

Node Manipulate structure and context in your mappings,

functions: for example: createIf (insert structuring elements) and
removeContexts (remove all higher-level contexts of a
source field).

Statistical Designed for source fields that occur more than once in the
functions: message-mapping source structure (maxOccurs = i > 1),
for example: sum (sum of values in a context), average
(average of values in a context), and count (number of
fields in a context).

Text Return or compare text strings in a message-mapping

functions: structure, for example: substring (return text string “A” for
“B”), concat (merge text strings), and compare (compare
text strings).

56 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Message-Mapping Functions

Exercise 5: Use Standard Message-

Mapping Functions
Exercise Objectives
After completing this exercise, you will be able to:
• Use the standard functions in graphical mapping

Business Example
A specific mapping task requires you to use standard functions in a graphical
mapping.

Task:
You want to create a graphical mapping between the message types Contact1 and
Customer1 by using standard functions.
1. Create a message mapping called ContactToCustomer1.
Reference the message type Contact1 as the source structure and the message
type Customer1 as the target structure. Both message types are in SWCV
SC_BIT_MAP, 1.0 in namespace urn:educationsap.com:bit:mapping (under
Basis Objects).

Hint: To select the source and target structures, select the message
type from the navigation tree and drag it to the relevant field using
drag and drop.

2. Connect source and target fields.

Create a graphical mapping between the source fields title, custname,
and firstname, and the target field fullname. The three fields should be
concatenated in this order with blanks separating them.
3. Connect source and target fields.
Create a graphical mapping between the source field contactID and the target
field customerNo. The mapping is to transfer the first 10 digits. An example
for the contents of the contactID field is the value 0123456789-181170.
4. Connect source and target fields.
Create a graphical mapping between the source field contactID and the target
field birthday. The last six digits of the source field are for the birthday date.
It should be stored in the format yyyy/dd/MM.
5. Connect source and target fields.
Continued on next page

2011 © 2011 SAP AG. All rights reserved. 57

Unit 2: Mapping Messages BIT460

Create an identical graphical mapping between the source fields firstname

and custname, and the target fields fullname and surname.
6. Test the mapping.
Use the mapping editor to test function. The field contactID should now
have the value 0123456789-181170.

58 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Message-Mapping Functions

Solution 5: Use Standard Message-

Mapping Functions
Task:
You want to create a graphical mapping between the message types Contact1 and
Customer1 by using standard functions.
1. Create a message mapping called ContactToCustomer1.
Reference the message type Contact1 as the source structure and the message
type Customer1 as the target structure. Both message types are in SWCV
SC_BIT_MAP, 1.0 in namespace urn:educationsap.com:bit:mapping (under
Basis Objects).

Hint: To select the source and target structures, select the message
type from the navigation tree and drag it to the relevant field using
drag and drop.

a) Create the new message mapping.

1. Expand the software component version SC_BIT_MAP, 1.0 .
2. In your namespace http://educationsap.com/pi/mapping##,
navigate to the Message Mappings node.
3. Create a new message mapping by calling the context menu and
choosing New....
4. Enter the name ContactToCustomer1 and your namespace
and choose Create.
b) Enter a description for the message mapping.
c) Specify a source message.
Drag the Contact1 message type to the field with the label Enter a
source message.
d) Specify a target message.
Drag the Customer1 message type to the field with the label Enter a
target message
2. Connect source and target fields.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 59

Unit 2: Mapping Messages BIT460

Create a graphical mapping between the source fields title, custname,

and firstname, and the target field fullname. The three fields should be
concatenated in this order with blanks separating them.
a) Select the fields to connect.
Drag the target field fullname to the data flow editor by using drag and
drop. Drag the title, custname, and firstname source fields individually
to the data flow editor by using drag and drop.
b) Select the function to use in the connection.
In the lower screen area of the data flow editor, choose Text Functions.
Select concat and drag the function to the data flow editor twice by
using drag and drop.
c) Connect the fields in the data flow editor as follows:
fullname = concat(concat(title, firstname), custname)
To separate the field contents with spaces, double-click both concat
functions and enter Space as the parameter.
3. Connect source and target fields.
Create a graphical mapping between the source field contactID and the target
field customerNo. The mapping is to transfer the first 10 digits. An example
for the contents of the contactID field is the value 0123456789-181170.
a) Select the fields to connect.
Drag the customerNo target field to the data flow editor by using drag
and drop. Drag the contactID source field to the data flow editor by
using drag and drop.
b) Select the function to use in the connection.
In the lower screen area of the data flow editor, choose Text Functions.
Select the substring function and drag it to the data flow editor by using
drag and drop.
c) Connect the fields in the data flow editor as follows:
customerNo = substring(contactID)
Use 0..10 as parameters in the substring function by double-clicking
the substring function and setting the Start Position to 0 and the
Character Count to 10.
4. Connect source and target fields.

Continued on next page

60 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Message-Mapping Functions

Create a graphical mapping between the source field contactID and the target
field birthday. The last six digits of the source field are for the birthday date.
It should be stored in the format yyyy/dd/MM.
a) Select the fields to connect.
Drag the birthday target field to the data flow editor by using drag and
drop. Drag the contactID source field to the data flow editor by using
drag and drop.
b) Select the function to use in the connection.
In the lower screen area of the data flow editor, choose Text Functions.
Select the substring function and drag it to the data flow editor by using
drag and drop.
c) Select the function to use in the connection.
In the lower screen area of the data flow editor, choose Date Functions.
Select the DateTrans function and drag it to the data flow editor by
using drag and drop.
d) Connect the fields in the data flow editor as follows:
birthday = DateTrans(Substring(contactID))
Use 11..17 as parameters in the substring function by double-clicking
the substring function and setting the Starting Position to 11 and the
Number of Characters to 6.

Hint: 11..17 is then displayed in the function display.

Use ddMMyy as the source format and yyyy/dd/MM as the target format
in the DateTrans function by double-clicking the DateTrans function
and entering ddMMyy as the inbound data format and yyyy/dd/MM as
the outbound data format.
5. Connect source and target fields.
Create an identical graphical mapping between the source fields firstname
and custname, and the target fields fullname and surname.
a) Drag the firstname target field to the firstname source field by using
drag and drop.
b) Drag the surname target field to the custname source field by using drag
and drop. Then save your mapping.
6. Test the mapping.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 61

Unit 2: Mapping Messages BIT460

Use the mapping editor to test function. The field contactID should now
have the value 0123456789-181170.
a) Create a new XML instance.
To create a new XML instance, choose the Test tab page and then
Create Instance. Expand the nodes in the XML instance and populate
the fields with test values.
b) Start the message-mapping test.
Execute the mapping by choosing Execute Mapping.

62 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Message-Mapping Functions

Lesson Summary
You should now be able to:
• Implement standard functions in your own message mappings
• Create and implement user-defined functions in message mappings

2011 © 2011 SAP AG. All rights reserved. 63

Unit Summary BIT460

Unit Summary
You should now be able to:
• Create a message mapping
• Use the mapping editor and explain how it works
• Test a message mapping
• Use trace information to help debug issues that arise during the testing
process
• Create and test a configuration scenario
• Implement standard functions in your own message mappings
• Create and implement user-defined functions in message mappings

64 © 2011 SAP AG. All rights reserved. 2011

 Unit 3
Advanced Mapping Concepts

Unit Overview

Unit Objectives
After completing this unit, you will be able to:
• Create a message mapping that makes use of contexts
• Set and delete the message-mapping context
• Use advanced options to help debug the message-mapping process
• Create user-defined functions and use them in the mapping editor
• Define and use both local and global user-defined functions
• Create function libraries and include them in a message mapping
• Change queues and contexts using standard and user-defined functions
• Work with mapping objects
• Output messages in the trace log

Unit Contents
Lesson: Using Contexts in Message Mapping ............................... 66
Exercise 6: Create a Message Mapping with Context Handling ...... 83
Lesson: Working with User-Defined Functions .............................. 88
Exercise 7: Create and Use Local User-Defined Functions ..........103
Exercise 8: Create and Use a Function Library ........................ 113
Exercise 9: Work with Local and Global User-Defined Functions ... 117
Exercise 10: Use variables in user-defined functions .................129

2011 © 2011 SAP AG. All rights reserved. 65

Unit 3: Advanced Mapping Concepts BIT460

Lesson: Using Contexts in Message Mapping

Lesson Overview
In this lesson, you learn how to use queues, contexts, and advanced options to help
improve the message-mapping process.

Lesson Objectives
After completing this lesson, you will be able to:
• Create a message mapping that makes use of contexts
• Set and delete the message-mapping context
• Use advanced options to help debug the message-mapping process

Business Example
You are responsible for the development of mappings in SAP NetWeaver Process
Integration and require an overview of the advanced message-mapping options
that queues and contexts provide.

Message-Mapping Structures and Elements

XML structures can contain substructures with multiple occurrences. This
multiple occurrence of structures or fields is particularly important when there are
source and target structures or fields with varying occurrences.

Hint: Even if elements can occur more than once in the XML instance
according to XML schema definition, they are only displayed once in the
structure overview. In the test area, you can use the context menu to copy
individual fields or entire subtrees, which allows you to create and test
them with any desired number of occurrences.

An icon precedes every field in the structure overview. These icons indicate the
status of a field, as illustrated in the following table:

Icon Types Used in the Structure View

Icon Meaning
Attributes

Elements
Elements with maxOccurs > 1
Nodes

66 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Contexts in Message Mapping

The figure Status of Fields, Attributes, and Nodes illustrates an example

structure with the corresponding icon types and colors.

Figure 18: Status of Fields, Attributes, and Nodes

The information displayed in Status of Fields, Attributes, and Nodes tells us the
following about the status of fields and nodes:
• Contactln node:
Contains an attribute with the name Type. Both icons are green, which
indicates that an assignment was already made.
• Name node:
Contains the two elements, Firstname and Surname. The red icon for both
elements indicates that they are mandatory fields, and that values still need to
be entered for them. This means the mapping is not yet complete.
• Surname field:
The field must be created and filled only once.
• Firstname field:
The field can be created and filled more than once.
• Occurrences column:
Indicates that all the target structure elements mentioned above must be
created and filled at least or exactly once.
• Address node

2011 © 2011 SAP AG. All rights reserved. 67

Unit 3: Advanced Mapping Concepts BIT460

The Address node and its subelements Street, CityCode, City, Phone, and
Email can be created in the target structure, since the minimum number of
occurrences is 0.

Hint: The icons preceding the Address fields are white indicating
that they do not have to be created in the target structure.

The following table summarizes the meaning associated with the icon color, for
example, green, red, or white.

Meaning of Icon Colors

Color Description
White Attribute or element not assigned
Red Attribute or element must be assigned to complete
the mapping
Yellow Attribute or element is assigned, but the
corresponding mapping in the data flow editor is not
complete
Green Target-field mapping is complete

Hint: The colors are only displayed in the target structure because the
mapping is a target-field mapping, responsible for creating a valid target
structure. Whether the source structure is valid can be checked with XML
validation as a pipeline step (not inside mapping).

Message-Mapping Queues
Message mapping is performed at runtime using queues. A queue contains all
values relating to a field in the message mapping. There is a queue for each XML
hierarchy level. If you have created an XML instance in the test environment
editor, you can display the various queues in the data flow editor. The following
queues can exist at message-mapping runtime:

• Source Structure:
A queue exists for each field in the source structure.
• Input and Result Queues:
Standard and user-defined functions process the input queues and write the
result of a calculation to a result queue; the result queue of one function can
also serve as the input queue for another function.
• Target Fields:

68 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Contexts in Message Mapping

A queue exists for the target field; the limitations of the target fields determine
which values from the target-field queue are written in the target structure.

Hint: Each field is determined by the field name and the structure
hierarchy in which it exists. If two fields have the same name but occur on
different levels (“paths”) then two separate queues are created.

The queue concept enables large XML messages to be processed quickly, since the
entire XML tree does not need to be built each time, only the values of a hierarchy
level. This can be done using a SAX parser; a DOM parser (which builds the entire
XML tree for an XML file) would use both too much memory and CPU time.

Input Queues with Different Lengths

If a source structure contains more than one instance of the same elements
(occurrence > 1), the context of a queue can contain multiple values. As long as
the input queues have the same number of values for each context, the way the
values are processed is clear-cut:

Figure 19: Queues with the Same Contexts

The input queues for the concat function in the following example have a different
number of values in the related contexts. If, for this reason, an input value from
a queue is missing for a function, the message mapping runtime simply uses the
last value that was read from the queue:

2011 © 2011 SAP AG. All rights reserved. 69

Unit 3: Advanced Mapping Concepts BIT460

Figure 20: Queues with Different Contexts

Hint: In both figures, the queues are read from right to left, which means
the values 1 and a are processed first.

The same also applies to generating functions (such as constants) that only
generate one value when they are linked to a function. If an additional input queue
has more than one value in a context, the mapping runtime simply reuses the last
value returned by the generating function.

Message-Mapping Contexts
The context of a field can also be understood as a type of association, that is,
as a description of the structure or hierarchy in which the field occurs. A field
can contain multiple contexts if the field exists in a series of structure levels
in a hierarchical manner. If a field is part of a structure that can have multiple
occurrences (occurrences > 1), this is referred to as a context change for the field.

Hint: If a field occurs more than once (occurrence > 1) within one
structure, this does not constitute a context change, since the field occurs
more than once within the same structure (that is, the same context).

If there is a context change within the hierarchy, this is shown in the relevant
queue. This concept is illustrated in detail in the figure Context Changes in XML
Files. For the item element, for example, there are two context changes, since the
item element occurs in the context of three nodes with the name A. This results in
two context changes for the queue on the hierarchy level of the item element.

70 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Contexts in Message Mapping

Figure 21: Context Changes in XML Files

The figure Complex Example of a Context Change illustrates the concept of

context change in more detail for a field “person” using the following contexts:
• Apartment Context:
In the context of the first apartment, Fix and Foxy are the people who live
there. There are four apartments in total, therefore three context changes.
• Street Context:
In the context of the first street, Fix, Foxy, Jolly Jumper, and Lucky Luke are
the residents. There are three streets in total, therefore two context changes.
• City Context:
In the context of the first city, Asterix, and Obelix are also residents. There
are two cities in total, therefore one context change.
• Root Context:
Valerian is only a resident in the context of the root element root. There is
no context change in this context.

2011 © 2011 SAP AG. All rights reserved. 71

Unit 3: Advanced Mapping Concepts BIT460

Figure 22: Complex Example of a Context Change

Context changes can be created and deleted with both standard functions and
user-defined functions. This enables a direct influence on the hierarchy levels
in the source message. User-defined functions are explained in more detail in
subsequent lessons.

Context Selection and Deletion

The mapping editor provides a selection of standard functions that you can use to
manipulate contexts (for example, to set and delete them), as follows:
• RemoveContexts()
Deletes all context changes in a queue.
• SplitByValue()
Inserts an additional context change after any value, any value change, or
any empty entry. You select one of these three options by setting the relevant
property in the function.
The standard function SplitByValue() can be regarded as the inverse function
of RemoveContexts().

Hint: Values can only be filled in open contexts; otherwise values are lost.
Open contexts are generated when the parent node is created.

72 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Contexts in Message Mapping

The figure Impact of the Standard Function RemoveContexts() on the

Message Mapping illustrates how the standard function RemoveContexts() works:
• RemoveContexts() Example 1:
In the first example for ,the standard function RemoveContexts() only the
values for the source field item of the first node header are used. The mapping
program creates the corresponding item target fields, and the contents of the
source fields are copied. In this case, the mapping stops (for this field) at the
first context change because node A can only occur once in this example.
• RemoveContexts() Example 2:
In the second example illustrating the standard function RemoveContexts(),
the context change is deleted by RemoveContexts(), which means the
contents of all the item source fields are transferred to the queue without a
context change. As a result, the transferred fields are all created as item
target fields and their values transferred accordingly.

Figure 23: Impact of the RemoveContexts() Standard Function on Message

Mapping

2011 © 2011 SAP AG. All rights reserved. 73

Unit 3: Advanced Mapping Concepts BIT460

The figure Impact of the Standard Function SplitByValue() on the Message

Mapping illustrates how the standard function SplitByValue() works.
• SplitByValue() is not used:
In the first example, four context changes are generated as required.
However, after the first context change, all four item source fields are saved
as item target fields and then populated with the relevant strings.
• SplitByValue() is used:
In the second example, SplitByValue() is used which results in a context
change after each source element item. Every target element item appears in
an individual context new_context.

Figure 24: Impact of the Standard Function SplitByValue() on the Message

Mapping

Explicit Context Selection

You can set the context of source fields explicitly in the data flow editor using the
menu displayed by clicking the secondary mouse button. The figure Impact of
Explicit Context Selection in the Message Mapping illustrates the effect on the
sample message type TestContext. Depending on whether you select segment,
parent, or TestContext as the context for the item source field, the queue has either
4, 1, or no context changes. If a higher context level is selected, the context

74 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Contexts in Message Mapping

changes located under this level are deleted. This method provides an elegant way
of solving the task of context selection for source fields, and enables users to avoid
multiple use of the standard function RemoveContexts() in the message mapping.

Figure 25: Impact of Explicit Context Selection in the Message Mapping

However, the function RemoveContexts() still has its advantages, since it proves
useful in target-field mappings comprised of function chains.
You use the exists() standard function to determine whether a particular source
field exists in the XML instance being processed. If it does, exists() returns true;
if it does not, it returns false. This is useful, for example, if you want to map an
optional source field to an obligatory target field because you can check whether
the field (not the contents) actually exists and if necessary, transfer a constant
instead.
The last standard function discussed here is copyValue(). For a field with
an occurrence of > 0, this function enables you to copy the individual values
separately to multiple target fields. If a source structure contains a field with the
name addrDat and the field has three values, you can map these three values to
the street, city, and zipcode target fields by using copyValue() (and specifying
an index):
/ns0:MT_B/street=CopyValue(/ns0:MT_A/addrDat, nnumber=0)
/ns0:MT_B/city=CopyValue(/ns0:MT_A/addrDat, nnumber=1)
/ns0:MT_B/zipcode=CopyValue(/ns0:MT_A/addrDat, nnumber=2)

2011 © 2011 SAP AG. All rights reserved. 75

Unit 3: Advanced Mapping Concepts BIT460

Target Structure Generation

In the mapping editor, you assign the fields of two XML structures to each other.
Note that at runtime no target structure exists prior to the mapping. The mapping
program creates the target structure only during execution of the mapping. This
means that the message mapping has to create the target structure at runtime. Two
things determine how the target structure looks after it has been created:
• Source structure:
The number and type of tags that exist in the source-structure instance
• Target structure:
The number of occurrences specified for the target fields in the target
structure
Whether the mapping program creates a particular structure field in the target
structure depends on the number of occurrences in the target structure and whether
a target-field mapping has been defined for this field. The following table provides
an overview of when you have to define target-field mappings for structure fields
according to the schema definition for the target structure.

Target-Field Mappings Required for Structure Fields in the Target

Structure
Occurrence Conditions for Creation
n = minOccurs = The message mapping creates these structure fields
maxOccurs > 0 automatically because they must occur n times in the
target structure independent of the target-field mapping.
You can still assign a target-field mapping to structure
fields of this type.
minOccurs = 0 The structure field is optional. Whether it is created
depends on whether you have assigned it a target-field
mapping. The following applies here:
• When you assign a target-field mapping to the
structure field, you also have to do this for
mandatory subelements/attributes, otherwise the
message mapping is incomplete.

76 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Contexts in Message Mapping

• To create optional structure fields, it is not

sufficient to create a target-field mapping for
subelements/attributes. The message mapping
suppresses optional structure fields without
target-field mappings including subnodes.
0 < minOccurs < You must define a target-field mapping for structure fields
maxOccurs of this type. How often these structure fields are created
depends on the minOccurs, maxOccurs, and target-field
mapping.

Hint: Before a node with minOccurs = 0 can be created in the target

structure, the message mapping must contain a function to create it, for
example, one of the standard functions that belong to the Constants
function category.

A simple mapping example should clarify the issues described above. The
following figure shows the source and target structures and the corresponding
mapping.

Figure 26: Creating the Target Structure - A Simple Mapping Example

To show more clearly how the target structure is created, an actual message from a
sender system is used here as a basis for creating the target fields.

Figure 27: Creating the Target Structure - Source Message

2011 © 2011 SAP AG. All rights reserved. 77

Unit 3: Advanced Mapping Concepts BIT460

Even though the MT_TargetMessage node has no target-field mapping, the

mapping program creates this node exactly once to match the number of
occurrences specified.

Figure 28: Creating the Target Structure - Number of Occurrences:

minOccurs = maxOccurs = 1

The number of occurrences for node B is between minOccurs = 0 and maxOccurs

= unbounded. However, since a target-field mapping is defined for node B, the
mapping program creates it in the target structure as often as required according to
the source structure and target-field mapping (in this case, three times).

78 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Contexts in Message Mapping

Figure 29: Creating the Target Structure - Number of Occurrences:

minOccurs = 0

Hint: The attribute setting minOccurs > 0 for a field does not necessarily
mean that the field will be existing in the target message. Assuming that
the field is part of a structure node with minOccurs = 0, and if no mapping
is assigned to that structure, neither the structure nor the subordinate fields
are created. In the example, this applies to node B and field item.

The number of occurrences for the item target field is between 1 and unbounded.
In practice, however, this field cannot be created an infinite number of times. How
often the mapping program creates this field in this case ultimately depends on the
corresponding source fields, how often they occur, and the relevant target-field
mapping.

2011 © 2011 SAP AG. All rights reserved. 79

Unit 3: Advanced Mapping Concepts BIT460

Figure 30: Creating the Target Structure - Number of Occurrences: 0 <

minOccurs < maxOccurs

The Message-Mapping Debug Process

Using the mapping editor, you can debug all steps in a message mapping by
displaying the contents of the relevant queues. For each element in the data flow
editor (both fields and functions) you can display the contents of the queue by
choosing Display Queue in the secondary mouse click (context menu).

Hint: Note that the term context menu refers to the menu that you navigate
to by right-clicking. The term context has two different meanings here.

The message mapping in the figure Message Mapping for the Target Field
Description illustrates an example of a more complex message mapping for the
target field Description.

80 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Contexts in Message Mapping

Figure 31: Message Mapping for the Target Field Description

First of all, the source field LANGKEY is compared with the constant EN. If this
comparison is successful, the contents of the source field TEXT are copied to
the target field Description. The figure Debugging View of the Target-Field
Mapping Description illustrates the contents of the corresponding queue. Based
on the contents of the queue equalsS the value [true] is only determined in the
second case. This means that the content toothpaste is copied from the middle
field TEXT to the target field Description. This result is represented in the queue
for the IfWithoutElse element.

Figure 32: Debugging View for the Description Target-Field Mapping

2011 © 2011 SAP AG. All rights reserved. 81

Unit 3: Advanced Mapping Concepts BIT460

In this example, it becomes visible that debugging of message mappings is

performed by displaying the queue. The result from each step of the message
mapping is represented in such a way that you can examine the transformation
from the source fields to the target fields in a step-by-step manner.
The displayed queue contains the following entries:
• Initial Context change:
The first gray entry represents the initial change that is not part of the
contents of the queue.
• Final context change:
The last black entry represents final context changes that is not part of the
contents of the queue.
• Suppressed entries:
The two turquoise entries are the suppressed entries; they result from the
[false] entries of the “if” part of the IfWithoutElse standard function.

82 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Contexts in Message Mapping

Exercise 6: Create a Message Mapping

with Context Handling
Exercise Objectives
After completing this exercise, you will be able to:
• Use contexts in a message mapping
• Use queues to help debug and test a message mapping

Business Example
A specific mapping task requires you to use queues and contexts to check a
message mapping.

Task:
Map a source message containing material data, a material number, and
descriptions in various languages to a target message containing the material
number and the description of the material in English.
1. Create a message mapping with the name MaterialToProductDef-
inition for software component version SC_BIT_MAP 1.0 in your
namespace http://educationsap.com/pi/mapping##.
The message mapping must reference the message type MATERIAL as
the source structure and the message type ProductDefinition as the target
structure.
2. Transfer the source field to the target field.
The message mapping requires that you first transfer the source field MATNO
to the target field RefNo. You then need to check the source field LANGKEY
for EN and copy the corresponding contents of the source field TEXT to
the target field Description.
3. Test the new message mapping.
Use the mapping editor test function to test the message mapping. For the
purposes of the test, create at least three different entries for the MATTEXT
node, and give each of them different values for the LANGKEY field, one of
which must be EN. Display the resulting queues.
4. Change the language for the Langtext of the material and test the mapping
again.

2011 © 2011 SAP AG. All rights reserved. 83

Unit 3: Advanced Mapping Concepts BIT460

Solution 6: Create a Message Mapping

with Context Handling
Task:
Map a source message containing material data, a material number, and
descriptions in various languages to a target message containing the material
number and the description of the material in English.
1. Create a message mapping with the name MaterialToProductDef-
inition for software component version SC_BIT_MAP 1.0 in your
namespace http://educationsap.com/pi/mapping##.
The message mapping must reference the message type MATERIAL as
the source structure and the message type ProductDefinition as the target
structure.
a) Create a new message mapping.
In your namespace http://educationsap.com/pi/mapping##, navigate
to the Message Mappings node. Create a new message mapping
by calling the context menu and choosing New.... Enter the name
MaterialToProductDefinition and your namespace and
choose Create. Enter a description.
b) Choose the source and target messages.
Drag the MATERIAL message type to the field with the label Choose a
Source Message. Drag the ProductDefinition message type to the field
with the label Choose a Target Message.
2. Transfer the source field to the target field.

Continued on next page

84 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Contexts in Message Mapping

The message mapping requires that you first transfer the source field MATNO
to the target field RefNo. You then need to check the source field LANGKEY
for EN and copy the corresponding contents of the source field TEXT to
the target field Description.
a) Map source and target fields.
Create an identical mapping between the source field MATNO and the
target field RefNo. Drag the RefNo target field to the MATNO source
field by using drag and drop.
b) Load the mapped fields into the data flow editor.
Load the Description target field into the data flow editor by
double-clicking it. Drag the TEXT and LANGKEY source fields to the
data flow editor by using drag and drop.
c) Set the mapping context.
Set the context for the source fields TEXT and LANGKEY to Material
by choosing Context → MATERIAL in the context menu.
d) Select the Text and Boolean message-mapping functions.
From the Text function category, choose the equalsS function, and from
the Boolean Functions area, choose the IfWithoutElse function, and
drag them to the data flow editor using drag and drop.
e) Select the Constant message-mapping function.
Select the Constant function from the Constant Functions area and drag
it to the data-flow editor by using drag and drop.
f) Connect source and target message-mapping fields.
Connect the fields in the data flow editor as follows:
Description = IfWithoutElse(equalsS(LANGKEY, Constant), TEXT)
Choose EN as the parameter for the Constant function by
double-clicking the Constant function and entering EN as the parameter.
Save your mapping.
3. Test the new message mapping.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 85

Unit 3: Advanced Mapping Concepts BIT460

Use the mapping editor test function to test the message mapping. For the
purposes of the test, create at least three different entries for the MATTEXT
node, and give each of them different values for the LANGKEY field, one of
which must be EN. Display the resulting queues.
a) Create a new XML instance.
Choose the Test tab page and create a new XML instance by choosing
Generate Instance. Create at least three different entries for the
MATTEXT node by clicking Duplicate Subtree with the secondary
mouse button. Expand the nodes in the XML instance and populate
the fields with test values.
b) Start the message mapping.
Start the mapping by choosing Execute Mapping. Choose Design and
double-click the target field Description. Call the context menu for the
functions displayed in the data-flow editor and choose Display Queue.
Track the contents of the queue for the entire message mapping.
4. Change the language for the Langtext of the material and test the mapping
again.
a) Confirm the message-mapping mode.
Make sure that the message mapping is in change mode.
b) Display the message mapping for the target field.
Open the existing mapping for the target field Description by
double-clicking the field to load it into the data flow editor.
c) Edit the Constant function.
Open the editor for the Constant function by double-clicking the field,
change the displayed value from EN to (for example) FR, and close
the editor.
d) Start the message mapping.
Repeat the message-mapping test as outlined in the previous step.

86 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Contexts in Message Mapping

Lesson Summary
You should now be able to:
• Create a message mapping that makes use of contexts
• Set and delete the message-mapping context
• Use advanced options to help debug the message-mapping process

2011 © 2011 SAP AG. All rights reserved. 87

Unit 3: Advanced Mapping Concepts BIT460

Lesson: Working with User-Defined Functions

Lesson Overview
This lesson shows how to use the mapping editor to employ user-defined
functions in message mappings. The lesson illustrates the difference between
local user-defined functions and global user-defined functions, which are created
in function libraries. The lesson also describes how you can use user-defined
functions to change queues and contexts.

Lesson Objectives
After completing this lesson, you will be able to:
• Create user-defined functions and use them in the mapping editor
• Define and use both local and global user-defined functions
• Create function libraries and include them in a message mapping
• Change queues and contexts using standard and user-defined functions
• Work with mapping objects
• Output messages in the trace log

Business Example
You are responsible for the development of mappings in SAP NetWeaver Process
Integration. You need to understand how to use advanced message-mapping
options to map field contents, including those for source and target structures with
different numbers of occurrences. You also need to know how to enhance standard
message-mapping functions with your own user-defined functions (and various
objects) to automate particular aspects of the message-mapping process.

User-Defined Message-Mapping Functions

If the existing standard functions do not fulfill the requirements for your
message-mapping needs, you can create your own user-defined functions in the
mapping editor. The functions contain Java source code that Enterprise Services
Repository saves for use in message mapping. Internally, the function is included
as a Java method in the Java code generated for the message mapping.

88 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

The parameters of a user-defined function such as the name, title, description, and
execution type are important.
• Function name:
The technical name (the name of the Java method)
• Function title:
The name of the function in the data flow editor
• Execution type:
Controls how the function behaves during message mapping
You create user-defined functions in the Functions tab of the message mapping.
You can define the number, names, and types of function transfer arguments in the
Signature Variables area. Once you have created a user-defined function, you can
use it in the Design tab (in the data flow editor) in the same way you would use
a standard function. The only difference is that the new user-defined function is
displayed in the User-Defined area in the list of standard functions.

Hint: You may define your own Category instead of User-defined.

The following figure shows how to create a user-defined function.

Figure 33: Creating User-Defined Functions in the Data-Flow Editor

A user-defined function is a Java method with an interface, consisting of the

parameters that you enter and the Container object. A user-defined function can
have multiple parameters, which are listed as method parameters in the editor

2011 © 2011 SAP AG. All rights reserved. 89

Unit 3: Advanced Mapping Concepts BIT460

window. You can use these parameters in the Java code by entering the names
specified in the interface (Name string, Surname string, ...). In this example, the
result must be returned as a string via return (depending on the Execution Type.
The figure above provides a simple example of the source code for a user-defined
function. The three input parameters are typed as String, are merged into one
string, and then returned by the function via return.
After you create a function, it is displayed in the Functions selection in the data
flow editor. You can delete or edit functions at any time, either in the Functions
tab, or in the Design tab, in the data flow editor.
Testing the message mapping (menu Message Mapping - Check or F7) will check
the java source code

Local and Global Functions

You can enhance the standard message-mapping functions by defining your own
additional local functions. A local user-defined function is only visible in the
message mapping for which the function was created.
You can also define global user-defined functions that are stored in function
libraries and available to all message mappings. A message mapping can include
all global function libraries and use their functions, which are themselves defined
in the same software-component version as the message mapping or an underlying
version. The overall process for defining a global user-defined function is as
follows:

1. Create a function library.

2. Define user-defined functions in the function library.
3. Include the function library in the message mapping.
4. Use (global) user-defined functions from the function library in the message
mapping.

Functions Libraries
A function library is a separate object type in Enterprise Services Repository
and can therefore be created via the context menu of, for example, a namespace
or software component version, for example: Context menu → New → Mapping
Objects → Function Library. You must assign a name to the function library and
then assign the function library to a software component version and one of the
namespaces contained therein.

Hint: You must ensure that the function library is located in the same
software component version as the message mappings you want to use
or an underlying version.

90 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

You define functions in the function library by making an entry in “Functions

and Java Areas” and giving the function a name. You can maintain the function
parameters and source code in the same way as for local user-defined functions, as
illustrated in the figure below.

Figure 34: Creating a (Global) User-Defined Function in a Function Library

After you create global user-defined functions in a function library, you can use
them in a message mapping. You can include function libraries in your message
mapping by making an entry in Used Function Libraries and using the input help
to select the function library required. The selected function library appears in the
Functions list in the mapping editor. When you select the function library from
the list, all the functions defined there appear in the mapping editor as pushbuttons
and can be used for the individual target-field mappings.

2011 © 2011 SAP AG. All rights reserved. 91

Unit 3: Advanced Mapping Concepts BIT460

Figure 35: Including Function Libraries in Message Mappings

Function Execution Types

When you create a user-defined function, you can use the Execution Type function
parameter to control how the function works internally. You can choose between
the execution types described in the following table:

Execution Type Description

Single Values All entries in an inbound queue are processed individually,
that is, the function is called internally as many times
as there are entries in the inbound queue. The function
returns a single value (string).
All Values of All values belonging to one context in an inbound queue
Context are processed together. The function is called as many
times as there are contexts in the inbound queue and each
context is transferred to the function as a string array. The
function returns a string array via the result outbound
parameter (of type ResultList).
All Values of All values in an inbound queue are transferred to the
Queue function together, that is, the function is executed only
once internally. The inbound queue is transferred to the
function as a string array. The function returns a string
array in the result outbound parameter (of type ResultList).

92 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

The following figure illustrates the concept of execution types using an inbound
queue as an example. The example shows how many times the function was called
internally for each of the execution types.

Figure 36: Effect of Different Execution Types on User-Defined Functions

(UDF)

Hint: Note that when large messages are processed, much cache memory
is required at runtime to save the entire queue. In such cases, it is better to
work with contexts.

The name of the Execution Type parameter has changed over the last few
releases. The table below shows the names used in the individual releases of
SAP NetWeaver Process Integration:

Release 3.0 7.0 7.1 and above

Name - Cache Execution Type
1. execution type Simple function Value Single Values
2. execution type Enhanced Context All Values of
function Context
3. execution type Enhanced Queue All Values of
function with Queue
“Save Entire
Queue in Cache”
indicator

2011 © 2011 SAP AG. All rights reserved. 93

Unit 3: Advanced Mapping Concepts BIT460

Result Queues and Parameters

If you create functions either of execution type All Values of Context or All Values
of Queue, you have to create the result queue (or parts of it) in the function
yourself using the result parameter. To help you, the ResultList Java class provides
methods and constants that you can use in the function.

• ResultList class methods:

– void addValue(String value)
– void addContextChange()
– void addSuppress()
– void clear()
• ResultList class constants:
– String ResultList.CC (context change)
– String ResultList.SUPPRESS (hidden element)
The addContextChange method appends the ResultList.CC constant to the
list (in Java, this is a static variable). The addSuppress method appends the
ResultList.SUPPRESS constant to the list. You cannot generate the target field and
its sub nodes for entries such as these.
The following example illustrates how the ResultList class methods and constants
are used; the example looks at the copyPerValueWithQueue function, which has
two input parameters (var1 and var2).
Based on the entries for var2, it is assumed that a context only ever contains one
value that is to be reproduced in the outbound queue. The reproduction of var2
shall be done as many times as there are entries in the corresponding context
in the queue of the var1 input parameter. This means that, in this example, the
following is true:
• Input parameter: Berlin
The entry Berlin from var2 is created in the result queue three times because
the first context for var1 has three entries.
• Input parameter: Mühlenhof
The entry Mühlenhof is created in the result queue twice because the second
context for var1 has two entries.
Since the function in this example has execution type All Values of Queue, the
inbound queues also contain all context changes represented in the string array
by the constant ResultList.CC. For this reason, it is essential to check within the
function whether the current line in the string array for parameter var1 refers
to a context change. If it does, a context change must also be carried out in the
inbound queue of parameter var2.

94 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

The outbound queue is set up using the addValue method of the result object,
which simply attaches the transferred single value to the outbound queue (string
array). The mapping task requires all values in the outbound queue to be separated
by a context change. You do this using the addContextChange method of the
result object.

Figure 37: Example of a User-Defined Function with Execution Type All

Values of Queue

When the inbound queue is transferred to a function, the first and last context
changes are suppressed, that is, the string array always starts and ends with an
entry for the relevant field. This also applies for the outbound queues to be created;
the first and last entries in the result string array must not be context changes.

Hint: In the mapping editor, context changes are indicated by dark gray
bars in the queues. However, the values of the previous entries are also
displayed in these bars, which may cause confusion at first.

Objects in user-defined functions

In addition to the parameters you define yourself, you can use a number of objects
belonging to the interface of user-defined functions to make additional generic
functions available. The following list shows some of the more commonly used
objects:

• Container:
The Container object can be used to create an AbstractTrace object as well
as a Map object.
• AbstractTrace:

2011 © 2011 SAP AG. All rights reserved. 95

Unit 3: Advanced Mapping Concepts BIT460

Transfer messages to the mapping trace. The trace is visible in message

monitoring, depending on the trace level.
• Map (runtime constants):
Access message mapping runtime constants.
• GlobalContainer:
You can use this object to cache the values that you want to read again when
you next call any user-defined function in the same message mapping.

Hint: Similar goals can be achieved with the Java Sections, so the
GlobalContainer will not be discussed in detail.

Container Object
The Container object belongs to the interface of user-defined functions, which
means you use the object to make available additional objects and user-defined
parameters.
The methods for the Container object are outlined in the following table.

Methods of the Container Class

Method Use
void setParameter (String Save parameters
parName, Object obj);
Object getParameter(String Read parameters
parName);
GlobalContainer Create a GlobalContainer
getGlobalContainer();
AbstractTrace getTrace(); Create an AbstractTrace object
java.util.Map Create a Map object
getTransformationParameters()

Trace Objects
In user-defined functions, you can use the AbstractTrace object to transfer
messages to the mapping trace. To create an AbstractTrace object, call the
getTrace() method for the container object.

96 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

Methods of the AbstractTrace Class

Method Use
void addInfo(String Transfer a message to the mapping trace
message); with trace level info
void addWarning(String Transfer a message to the mapping trace
message); with trace level warning
void Transfer a message to the mapping trace
addDebugMessage(String with trace level debug
message);

Examples of Trace Messages from a

User-Defined Function

...
AbstractTrace at = container.getTrace();
at.addInfo( "This is an information" );
at.addWarning( "This is a warning!" );
at.addDebugMessage( "This is a debug message" );
...

You can display the messages that you write to the trace with these methods in the
test environment, for example. You can also set a trace level for each pipeline so
that the trace messages are written to the trace header of the message at runtime.
The trace levels 0 to 3 are associated with the trace levels info, warning, and
debug as follows:

Trace Level of the Pipeline and Mapping Trace

Pipeline Mapping Trace
0 No trace
1 addWarning() entries written to trace
2 addWarning() and addInfo() entries written to trace
3 addWarning() and addInfo() and addDebugMessage()
entries written to trace

Map Objects
A map object enables you to access message-mapping runtime constants. Some
mapping programs need to access fields in the message header. To facilitate this,
the mapping runtime stores the values of the fields as key-value pairs.

2011 © 2011 SAP AG. All rights reserved. 97

Unit 3: Advanced Mapping Concepts BIT460

Examples of Key-Value Pairs in the Map for Runtime Constants

Key Value
“MessageClass” “ApplicationMessage”
“ProcessingMode” “synchronous”
“ReceiverNamespace” “http://demo.com/xi/example”

To read the fields of the message header at runtime, you must access the map for
the runtime constants. However, accessing the map using the key literals listed
above would render the program code invalid if a key is changed at some point
in the future. As an alternative, the mapping API provides string constants that
you can use instead of key literals to access the map.

Examples of Runtime Constants

String Constants Key Meaning
SENDER_SERVICE “SenderService” Sender service
RECEIVER_NAME “ReceiverName” Receiver interface
INTERFACE “Interface” Sender interface

You can use the map object to access runtime constants in user-defined constants.
The map object is created using either the Container object or a GlobalContainer
as illustrated in the following code example:

Accessing the Map Object

String headerField;
java.util.Map map;

map = container.getTransformationParameters();

headerField = (String) map.get(

StreamTransformationConstants.INTERFACE_NAMESPACE);

AbstractTrace at = container.getTrace();
at.addInfo(headerField);
return a;

Hint: The user-defined function's input parameter (string a) is returned

unchanged. The parameter is only used to allow the function to be called
and executed; in this particular example, the assigned value is not changed.

98 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

Java Sections
When you create a local user-defined function in a message mapping, the system
creates a Java class in the background. You can define attributes in this Java class
that can then be used in all user-defined functions for this message mapping.
When this class is created, two methods are also created automatically: init and
cleanUp. When the mapping is run, these two methods are called automatically:
init is called prior to the message mapping and cleanUp is called afterwards, for
example, to remove data from the memory that is no longer required once the
message mapping is complete. Initially, neither method contains source code, but
you can program this yourself.
The Java sections can be found in the message mapping on the Functions tab
page. Here you can define, for example, the interface of the init method and the
source code.

Figure 38: Java Sections in Message Mapping

Java sections do not exist only in (local) user-defined functions; every function
library has its own Java sections. If you use multiple function libraries in one
message mapping, there are multiple areas in which attributes and methods are
defined, as well as multiple init and cleanUp methods. This source code is run
either at the start or end of the mapping runtime based on the order in which you
have entered the relevant function libraries in the table that defines library usage.

External Java Classes

You can also use external classes in user-defined functions. These classes are
developed in one package, for example in the SAP NetWeaver Developer Studio,
compiled and then exported as JAR files from SAP NetWeaver Developer Studio.
These JAR files can then be uploaded to Enterprise Services Repository in an

2011 © 2011 SAP AG. All rights reserved. 99

Unit 3: Advanced Mapping Concepts BIT460

imported archive. In the figure below, a class called myClass is uploaded

from the myPackage package to imported archive IA_MyPackage as JAR file
extJavaClass.jar.

Figure 39: Importing Externally-Developed Java Classes Using Imported

Archives

Hint: Imported archives can be used in a message mapping or function

library if they come from the same software component version or an
underlying version.

After Java classes have been imported in this way, you can use them in the message
mapping by entering the relevant imported archive in the message mapping in
the Archives Used area on the Functions tab page. You then have to specify the
relevant class and package name in the Import Instructions area. You can then use
all the methods of this class in the user-defined methods for the message mapping.
In the following example, the addCounter method of the imported class myClass
is to be used in the user-defined function addCounter. First, go to the Archives
Used area and enter the imported archive IA_MyPackage mentioned above.
Then go to the Import Instructions area and enter the package and class name
myPackage.myClass.

100 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

Figure 40: Using External Java Classes in User-Defined Functions

Hint: Complex user-defined functions should be developed in SAP

NetWeaver Developer Studio, for example, and then imported as described
above. This is because SAP NetWeaver Developer Studio has a debugger
function and test environment.

2011 © 2011 SAP AG. All rights reserved. 101

Unit 3: Advanced Mapping Concepts BIT460

102 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

Exercise 7: Create and Use Local

User-Defined Functions
Exercise Objectives
After completing this exercise, you will be able to:
• Create and use local user-defined functions in a message mapping

Business Example
A specific mapping task requires you to use queues, contexts, and user-defined
functions in message mapping.

Task:
The source message contains purchase order information. It can contain multiple
purchase orders. Each purchase order has header information and several ordered
objects. The target message is a table containing the same number of rows as there
are ordered objects. Each row contains the relevant header information for the
corresponding purchase order.
This kind of mapping program is very useful for processing IDocs in tables. Here,
too, the header information has to be added for each IDoc entry in the row.
There are numerous ways to handle this mapping task. The solution described here
is just one of these many possibilities.
1. Create a new message mapping.
Create a message mapping with the name PurchaseOrderToResultset
in software component version SC_BIT_MAP, 1.0 in your namespace
http://educationsap.com/pi/mapping##. In the message mapping, reference
the message type PurchaseOrder as the source structure and the message
type resultset as the target structure.
2. Map the message fields.
Create an identical mapping between the source and target fields Material,
Units, and Price.
3. Remove context of source object item.
To create exactly the same number of rows row as objects item, you have
to move the source field item from its context in the message mapping and
connect it to the target field row.
4. Create a user-defined function with the name copyPerValue.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 103

Unit 3: Advanced Mapping Concepts BIT460

To make sure that the header entries of the individual source objects are
copied enough times, you can create a user-defined function with the name
copyPerValue. You use that function to copy any source field to an array,
as specified by the number of item source fields.
5. Define the user function.
Combine the copyPerValue function with the source fields Name and Address
and the SplitByValue function so that the correct number of target fields
name and address are created in the target structure.
6. Test the mapping by using the mapping editor test function.
7. Additional Task I:
Create another user-defined function and name it copyPerValueWithQueue.
In this function, do not use the SplitByValue function as you did in Step 6,
but enter the relevant code to handle the context changes in the source text.
8. Additional Task II:
Instead of your user-defined function copyPerValue, use the standard
function useOneAsMany for the Name target-field mapping.

104 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

Solution 7: Create and Use Local

User-Defined Functions
Task:
The source message contains purchase order information. It can contain multiple
purchase orders. Each purchase order has header information and several ordered
objects. The target message is a table containing the same number of rows as there
are ordered objects. Each row contains the relevant header information for the
corresponding purchase order.
This kind of mapping program is very useful for processing IDocs in tables. Here,
too, the header information has to be added for each IDoc entry in the row.
There are numerous ways to handle this mapping task. The solution described here
is just one of these many possibilities.
1. Create a new message mapping.
Create a message mapping with the name PurchaseOrderToResultset
in software component version SC_BIT_MAP, 1.0 in your namespace
http://educationsap.com/pi/mapping##. In the message mapping, reference
the message type PurchaseOrder as the source structure and the message
type resultset as the target structure.
a) Create the new message mapping:
In your namespace http://educationsap.com/pi/mapping##, navigate
to the Message Mappings node. Create a new message mapping
by calling the context menu and choosing New.... Enter the name
PurchaseOrderToResultset and your namespace and choose
Create.
b) Select the message types to map.
Enter a description. Drag the PurchaseOrder message type to the field
with the label Enter a source message. Drag the resultset message type
to the field with the label Enter a target message.
2. Map the message fields.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 105

Unit 3: Advanced Mapping Concepts BIT460

Create an identical mapping between the source and target fields Material,
Units, and Price.
a) Drag the material target field to the Material source field by using
drag and drop.
b) Drag the units target field to the Units source field by using drag and
drop.
c) Drag the price target field to the Price source field by using drag and
drop.
3. Remove context of source object item.
To create exactly the same number of rows row as objects item, you have
to move the source field item from its context in the message mapping and
connect it to the target field row.
a) Load the source and target fields.
Load the row target field into the data-flow editor by double-clicking
it. Drag the item source field to the data-flow editor by using drag and
drop.
b) Locate the removeContexts function.
In the lower screen area of the data-flow editor, choose Node Functions.
Select the removeContexts function and drag it to the data-flow editor
by using drag and drop.
c) Include the removeContexts function.
Connect the fields in the data-flow editor as follows:
row = removeContexts(item)
4. Create a user-defined function with the name copyPerValue.

Continued on next page

106 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

To make sure that the header entries of the individual source objects are
copied enough times, you can create a user-defined function with the name
copyPerValue. You use that function to copy any source field to an array,
as specified by the number of item source fields.
a) Create the user-defined function copyPerValue.
Create a user-defined function by selecting the relevant icon in the
toolbar at the bottom of the data-flow editor. Enter copyPerValue as the
name and copyPerValue as the title to appear in the data-flow editor.
Fill the Description field and set the Execution Type field to All Values
of Context. Using the first icon, insert a second argument var2 of type
string after argument var1. Choose Create Function.
b) Define the user function copyPerValue.
Enter the following source code in the new user-defined function :
for (int i=0; i<var1.length; i++) {
result.addValue(var2[0]);
}

c) Save the user-defined function copyPerValue.

Choose Close and save your mapping.
5. Define the user function.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 107

Unit 3: Advanced Mapping Concepts BIT460

Combine the copyPerValue function with the source fields Name and Address
and the SplitByValue function so that the correct number of target fields
name and address are created in the target structure.
a) Specify source and target fields.
Load the name target field into the data-flow editor by double-clicking
it. Drag the source fields Name and item to the data-flow editor by
using drag and drop.
b) Specify a user-defined function.
In the lower screen area of the data-flow editor, choose User-Defined
Functions. Select the copyPerValue function and drag it to the data-flow
editor by using drag and drop.
c) Specify a node function.
In the lower screen area of the data-flow editor, choose Node Functions.
Select the SplitByValue function and drag it to the data-flow editor by
using drag and drop.
d) Define the function usage.
Connect the fields in the data-flow editor as follows:
name = SplitByValue(copyPerValue(item, Name))
e) Specify source and target fields.
Load the address target field into the data-flow editor by double-clicking
it. Drag the source fields Address and item to the data-flow editor by
using drag and drop.
f) Specify a user-defined function.
In the lower screen area of the data-flow editor, choose User-Defined
Functions. Select the copyPerValue function and drag it to the data-flow
editor by using drag and drop.
g) Specify a node function.
In the lower screen area of the data-flow editor, choose Node Functions.
Select the SplitByValue function and drag it to the data-flow editor by
using drag and drop.
h) Define the function usage.
Connect the fields in the data-flow editor as follows:
address = SplitByValue(copyPerValue(item, Address))
Save your mapping.

Continued on next page

108 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

6. Test the mapping by using the mapping editor test function.

a) Create a new XML instance.
Choose the Test tab page and create a new XML instance by choosing
Create Instance. Expand the nodes in the XML instance and use the
context menu to copy the Order node once and the item node at least
once for each order. Fill all fields in the XML instance with test values,
choose Add Test Instance, and save this test message as a test case Test1
for use in later tests.
b) Start the test.
Execute the message-mapping test by choosing Start Transformation.
7. Additional Task I:
Create another user-defined function and name it copyPerValueWithQueue.
In this function, do not use the SplitByValue function as you did in Step 6,
but enter the relevant code to handle the context changes in the source text.
a) Create a user-defined function.
Create a user-defined function by choosing the relevant icon beside
the Functions text in the lower toolbar of the data-flow editor. Select
copyPerValueWithQueue as the name and copyPerValueWithQueue as
the title. Fill the Description field and set the Execution Type field to
All Values of Queue. Using the first icon, insert a second argument var2
of type string after argument var1. Choose Create Function.
b) Define the new user function.
Enter the following source code:
int var2_counter = 0;
for ( int i=0; i<var1.length; i++ ) {
if ( var1[i] == ResultList.CC ) {
var2_counter = var2_counter + 2;
}
else {
result.addValue( var2[var2_counter] );
if ( i<var1.length-1 )
result.addContextChange();
}
}

c) Save the message mapping

Choose Close to save the changes to your message mapping.
d) Delete the mapping for the address target field.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 109

Unit 3: Advanced Mapping Concepts BIT460

Load the target field into the data-flow editor by double-clicking it,
remove the connecting arrow from the address target field, and remove
the source fields by choosing Delete Floating Objects on the left-hand
side of the data flow editor.
e) Select the source fields to map.
Drag the source fields Address and item to the data-flow editor by using
drag and drop.
f) Select the user-defined function.
In the lower screen area of the data-flow editor, choose User-Defined
Functions. Select copyPerValueWithQueue and drag the function to the
data-flow editor by using drag and drop.
g) Assign the user function.
Connect the fields in the data-flow editor as follows:
address = copyPerValueWithQueue(item, Address)
h) Save the message mapping.
i) Test the message mapping.
Choose the Test tab page and use the test case already created to test
your change by choosing Start Transformation.
8. Additional Task II:

Continued on next page

110 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

Instead of your user-defined function copyPerValue, use the standard

function useOneAsMany for the Name target-field mapping.
a) Delete the mapping for the Name target field.
Load the Name field into the data flow editor by double-clicking it,
remove the connecting arrow from the Address target field, and remove
the source fields by choosing Delete Floating Objects.
b) Select the source fields.
Drag the Name source field to the data flow editor and drag the Material
source field twice by using drag and drop.
c) Select a standard function.
In the lower screen area of the data flow editor, choose Node Functions.
Select useOneAsMany and drag the function to the data flow editor by
using drag and drop.
d) Define the user function.
Connect the fields in the data flow editor as follows:
name = useOneAsMany(name, Material, Material)
e) Set the context.
Set the context for Material (top field icon) to Order by choosing
Context → Order from the context menu.
f) Save the target-field mapping.
g) Test the mapping.
Choose the Test tab page and use the test case already created to test
your change by choosing Start Transformation.

2011 © 2011 SAP AG. All rights reserved. 111

Unit 3: Advanced Mapping Concepts BIT460

112 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

Exercise 8: Create and Use a Function

Library
Exercise Objectives
After completing this exercise, you will be able to:
• Create function libraries
• Use function library functions in a message mapping

Business Example
In your company, you are responsible for mapping and have to process mappings
for different scenarios. When doing so, you realize that you sometimes need to use
the same user-defined functions in different message mappings.

Task:
For the message mapping in this task, you need a copy of the local
user-defined function copyPerValue that was defined in the message mapping
PurchaseOrderToResultset in the previous exercise. You need to create a function
library containing the new global copyPerValue function. You must include your
new function library in the message mapping PurchaseOrderToResultset and
replace the local user-defined function copyPerValue with the global user-defined
function of the same name.
1. Create a function library.
Create function library FL_## in your namespace http://education-
sap.com/pi/mapping##.
2. Create a global function.
In your function library FL_## (namespace http://educationsap.com/pi/map-
ping##), create a global function called copyPerValue that has the same
interface, properties, and code as the local function copyPerValue from your
PurchaseOrderToResultset message mapping.
3. Include the new global function in the message mapping.
In your PurchaseOrderToResultset message mapping, replace the local
user-defined function copyPerValue with the corresponding global function
from your function library FL_##.
4. Test your message mapping PurchaseOrderToResultset.

2011 © 2011 SAP AG. All rights reserved. 113

Unit 3: Advanced Mapping Concepts BIT460

Solution 8: Create and Use a Function

Library
Task:
For the message mapping in this task, you need a copy of the local
user-defined function copyPerValue that was defined in the message mapping
PurchaseOrderToResultset in the previous exercise. You need to create a function
library containing the new global copyPerValue function. You must include your
new function library in the message mapping PurchaseOrderToResultset and
replace the local user-defined function copyPerValue with the global user-defined
function of the same name.
1. Create a function library.
Create function library FL_## in your namespace http://education-
sap.com/pi/mapping##.
a) Navigate to your namespace.
In Enterprise Services Repository, navigate to your namespace
http://educationsap.com/pi/mapping## in SWCV SC_BIT_MAP, 1.0.
b) Create the function library.
In the context menu for your namespace, choose New → Mapping
Objects → Function Library and create a new function library entitled
FL_##.
c) Save the function library.
Enter a meaningful description and save your function library.
2. Create a global function.

Continued on next page

114 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

In your function library FL_## (namespace http://educationsap.com/pi/map-

ping##), create a global function called copyPerValue that has the same
interface, properties, and code as the local function copyPerValue from your
PurchaseOrderToResultset message mapping.
a) Add a function to the global function library.
In your function library FL_##, go to Functions and Java Areas and
add another entry to the list by choosing Insert Line Below Selection.
Enter the name of the copyPerValue function here.
b) Name the new global function.
In the right-hand screen area, enter the title copyPerValue and a
suitable description. Set the Execution Type field to All Values
of Context.
c) Add a parameter to the new global function.
Add an additional argument of type String to the existing argument
var1 by choosing Insert Line Below Selection and name this var2.
d) Define the new global function.
In your message mapping PurchaseOrderToResultset, navigate to the
local function copyPerValue, copy the code, and paste it in the editor
area of your global function copyPerValue.
e) Save your function library.
3. Include the new global function in the message mapping.
In your PurchaseOrderToResultset message mapping, replace the local
user-defined function copyPerValue with the corresponding global function
from your function library FL_##.
a) Display the list of global function libraries.
In your message mapping PurchaseOrderToResultset (namespace
http://educationsap.com/pi/mapping##), navigate to the mapping editor
and choose Show Used Function Libraries (top left button).
b) Add the newly created global function library.
Switch to change mode and add a new line to the Function Libraries
Used area that is currently open by choosing Insert Line Below
Selection. Use the input help for the Function Library field to fill the
new line with the function library FL_## that you created in the second
part of this task.
c) Include a new (global) function in a target field.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 115

Unit 3: Advanced Mapping Concepts BIT460

Navigate to the target-field mapping for the name target field and
replace the local user-defined function copyPerValue with the global
function copyPerValue from your function library FL_##.
1. In the Functions field of the mapping editor, select FL_## and
double-click copyPerValue so that the global function is displayed
in the target-field mapping for the name field.
2. Remove all connections for the local function copyPerValue and
connect it to the relevant box of the global function copyPerValue.
3. Delete the floating objects by choosing the relevant pushbutton on
the right-hand side of the mapping editor.
d) Include a new (global) function in a target field.
Navigate to the target-field mapping for the Address target field and
replace the local user-defined function copyPerValue with the global
function copyPerValue from your function library FL_##.
1. In the Functions field of the mapping editor, select FL_## and
double-click copyPerValue so that the global function is displayed
in the target-field mapping for the Address field. .
2. Remove all connections for the local function copyPerValue and
connect it to the relevant box of the global function copyPerValue.
3. Delete the floating objects by choosing the relevant pushbutton on
the right-hand side of the mapping editor.
e) Remove the reference to the unused local function.
In the Functions field of the mapping editor, select User-Defined and
delete your local function copyPerValue by opening the selection menu
for the copyPerValue button and choosing Delete Function.
f) Save your message mapping.
4. Test your message mapping PurchaseOrderToResultset.
a) Choose the Test tab page and use the test data from the previous exercise
to test your message mapping by choosing Start Transformation
(bottom left).

116 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

Exercise 9: Work with Local and Global

User-Defined Functions
Exercise Objectives
After completing this exercise, you will be able to:
• Create and use local user-defined functions in a message mapping
• Include and use global user-defined functions in message mappings

Business Example
A specific mapping task requires you to use local and global user-defined functions
in graphical mapping.

Task:
The source message contains purchase order information. This contains header
information and multiple detailed purchase orders. Each of these detailed purchase
orders contains a supplier name. Each supplier can have multiple purchase
orders, and the exact number of suppliers in the source message is unknown. In
addition, the purchase orders are not sorted according to supplier. The target
message contains a purchase order for each supplier. Each entry for a supplier is to
contain the header information from the source message and the corresponding
purchase orders.
There are numerous ways to handle this mapping task. The solution described here
is just one of these many possibilities.
1. Create a message mapping with the name OrderToSortedOrder.
2. Specify the source and target message type.
3. Determine the number of suppliers; this establishes the required number of
target fields Orders.
Create a user-defined function with the name getSuppliers with the
input parameter supplier (and Execution Type = All Values of Context). This
function tests all Supplier source fields and returns each supplier only once.
4. Assign the header information to each Orders purchase order in the target
structure:
The global function copyPerValue from the function library FL_## created in
the last exercise is to be used later in this step. For this reason, you should
include this function library in your message mapping now.
5. Determine the number of target fields Items for each supplier.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 117

Unit 3: Advanced Mapping Concepts BIT460

Create a user-defined function with the name assignItems with the

input parameter supplier (and Execution Type=All Values of Context). This
function determines the number of purchase orders for a supplier and
separates them with a context change. A list of target fields Items is to be
created for each supplier.
6. Assign the purchase order information for each order Orders to each target
field item:
Create a user-defined function with the name assignSupplier
(Execution Type = All Values of Context) with the input parameter
supplier. This function is to assign the source fields of the source
structure Detail to the corresponding target fields of the target structure Items.
7. Execute the message mapping for the individual target fields; to complete the
mapping program, you need eight graphical mappings.

Hint: Use the explicit context change for POCombined for all source
fields under the Detail source node (Supplier, ProductID, Quantity,
Price), so that all source fields are available in the main context.

8. Test the mapping by using the mapping editor test function. For test
purposes, use a header and four details with two different Suppliers.

118 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

Solution 9: Work with Local and Global

User-Defined Functions
Task:
The source message contains purchase order information. This contains header
information and multiple detailed purchase orders. Each of these detailed purchase
orders contains a supplier name. Each supplier can have multiple purchase
orders, and the exact number of suppliers in the source message is unknown. In
addition, the purchase orders are not sorted according to supplier. The target
message contains a purchase order for each supplier. Each entry for a supplier is to
contain the header information from the source message and the corresponding
purchase orders.
There are numerous ways to handle this mapping task. The solution described here
is just one of these many possibilities.
1. Create a message mapping with the name OrderToSortedOrder.
a) In software component version SC_BIT_MAP 1.0 in your namespace
http://educationsap.com/pi/mapping##, navigate to the Message
Mappings node.
b) Add a new message mapping by displaying the context menu and
choosing New.... Enter the name OrderToSortedOrder and your
namespace.
c) Choose Create and enter a description.
2. Specify the source and target message type.
a) Use POCombined as the source message type.
Drag message type POCombined from SWCV SC_BIT_BASE_COMP,
1.0 to the Enter a Source Message area using drag and drop.
b) Use POSplit as the target message type.
Drag message type POSplit from SWCV SC_BIT_BASE_COMP, 1.0 to
the Enter a Target Message area using drag and drop.
3. Determine the number of suppliers; this establishes the required number of
target fields Orders.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 119

Unit 3: Advanced Mapping Concepts BIT460

Create a user-defined function with the name getSuppliers with the

input parameter supplier (and Execution Type = All Values of Context). This
function tests all Supplier source fields and returns each supplier only once.
a) Create a user-defined function:
1. Select the relevant icon beside Functions in the lower toolbar
of the data flow editor.
2. Select getSuppliers as the name and title, fill the Description field.
3. Set the Execution Type field to All Values of Context, and change
the name of argument var1 to supplier (in the Signature
Variables area).
4. Choose Create Function to create the new function.
b) Define the mapping function.
To define the mapping function, enter the following source code:
/* Use vector to test values
and save them once in vector */

Vector v = new Vector();

for (int i=0; i<supplier.length; i++) {
if ( !v.contains(supplier[i]) )
v.add(supplier[i]);
}
/* Add content of vector to result*/

for (int i=0; i<v.size(); i++) {

result.addValue( (String)v.get(i) );
}

c) Save the function; choose Close.

4. Assign the header information to each Orders purchase order in the target
structure:

Continued on next page

120 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

The global function copyPerValue from the function library FL_## created in
the last exercise is to be used later in this step. For this reason, you should
include this function library in your message mapping now.
a) List the currently used function libraries.
Choose Show Used Function Libraries (top left pushbutton in the
mapping editor) and insert a new line in the Function Libraries Used
area that is currently open by choosing Insert Line Below Selection.
b) Insert the new function library.
Use the input help for the Function Library field to fill the new line
with the function library FL_## that you created in the last exercise.
5. Determine the number of target fields Items for each supplier.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 121

Unit 3: Advanced Mapping Concepts BIT460

Create a user-defined function with the name assignItems with the

input parameter supplier (and Execution Type=All Values of Context). This
function determines the number of purchase orders for a supplier and
separates them with a context change. A list of target fields Items is to be
created for each supplier.
a) Create a user-defined function:
1. Select the relevant icon beside Functions in the lower toolbar
of the data flow editor.
2. Select assignItems as the name and title, fill the Description field,
set the Execution Type field to All Values of Context, and change
the name of argument var1 to supplier (in the Signature
Variables area).
3. Choose Create Function to create the function.
b) Define the new function
To define the new function, enter the following source code:
/* Use vector to test values
and save them once in vector. */

Vector v = new Vector();

for (int i=0; i<supplier.length; i++) {
if ( !v.contains(supplier[i]) )
v.add(supplier[i]);
}

/* Determine if items belong to the current

supplier v.get(i).
Each supplier group is delimited with a
different context. */

for (int i=0; i<v.size(); i++) {

String s = (String) v.get(i);
for (int j=0; j<supplier.length; j++) {
if (s.equals(supplier[j]))
result.addValue("");
}
result.addContextChange();
}

c) Save the function; choose Close.

6. Assign the purchase order information for each order Orders to each target
field item:

Continued on next page

122 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

Create a user-defined function with the name assignSupplier

(Execution Type = All Values of Context) with the input parameter
supplier. This function is to assign the source fields of the source
structure Detail to the corresponding target fields of the target structure Items.
a) Create a user-defined function:
1. Select the relevant icon beside Functions in the lower toolbar
of the data-flow editor.
2. Choose assignSuppliers as the function name and title, fill the
Description field, and set the Execution Type to All Values of
Context.
3. Change the name of argument var1 to supplier, and add a
second argument with the name detailField (Java type
String).
4. Choose Create Function.
b) Define the new function.
To define the new user function, enter the following source code:
/* Use vector to test values
and save them once in vector */

Vector v = new Vector();

for (int i=0; i<supplier.length; i++) {
if ( !v.contains(supplier[i]) )
v.add(supplier[i]);
}
/* Determine whether the value detailField[i]
of the second parameter belongs to the current
supplier v.get(i).
If this is the case, the second parameter
detailField[i] is added to the result Array. */

for (int i=0; i<v.size(); i++) {

String s = (String) v.get(i);
for (int j=0; j<supplier.length; j++) {
if ( s.equals(supplier[j]) )
result.addValue(detailField[j]);
}
}

c) Save the function; choose Close.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 123

Unit 3: Advanced Mapping Concepts BIT460

7. Execute the message mapping for the individual target fields; to complete the
mapping program, you need eight graphical mappings.

Hint: Use the explicit context change for POCombined for all source
fields under the Detail source node (Supplier, ProductID, Quantity,
Price), so that all source fields are available in the main context.

a) Connect the target field Orders and the source field Supplier:
1. Drag the target field Orders and the source field Supplier to the
data-flow editor by using drag and drop.
2. In the lower part of the data flow editor, choose the User-Defined
function category, then the getSuppliers function, and drag this to
the data flow editor by using drag and drop.
3. Connect the fields in the data-flow editor as follows: Orders =
getSuppliers (Supplier).
4. Make sure that the context for the Supplier field is set to
POCombined.
b) Connect the target field Header and the source field Supplier:
1. Drag the target field Header and the source field Supplier to the
data flow editor by using drag and drop.
2. In the lower part of the data flow editor, choose the User-Defined
function category, then the getSuppliers function, and drag this to
the data flow editor by using drag and drop.
3. Select the SplitByValue function from the Node Functions area
and drag it to the data flow editor by using drag and drop.
4. Connect the fields in the data flow editor as follows: Header =
SplitByValue(getSuppliers(Supplier)).
5. Make sure that the context for the Supplier field is set to
POCombined.
c) Connect the target field toCompany and the source field Supplier:
1. Drag the target field toCompany and the source field Supplier to
the data-flow editor by using drag and drop.
2. Choose the getSuppliers function from the User-Defined function
category and the SplitByValue function from the Node Functions
area and drag them to the data-flow editor by using drag and drop.
3. Connect the fields in the data-flow editor as follows: toCompany
= SplitByValue(getSuppliers(Supplier)).
4. Make sure that the context for the Supplier field is set to
POCombined.

Continued on next page

124 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

d) Connect the target field custName and the source fields Supplier and
Name:
1. Drag the target field custName and the source fields Supplier and
Name to the data-flow editor by using drag and drop.
2. Under the User-Defined function category, select the getSuppliers
function and drag it to the data-flow editor by using drag and drop.
3. Under the FL_## function category, select the global function
copyPerValue from your function library and drag it to the
data-flow editor by using drag and drop.
4. Select the SplitByValue function from the Node Functions area
and drag it to the data-flow editor by using drag and drop.
5. Connect the fields in the data-flow editor as follows: CustName =
SplitByValue(copyPerValue(getSuppliers(Supplier), Name)).
6. Make sure that the context for the Supplier field is set to
POCombined.
e) Connect the target field custAddress and the source fields Supplier and
Address:
1. Drag the target field custAddress and the source fields Supplier
and Address to the data-flow editor by using drag and drop.
2. Under the User-Defined function category, select the getSuppliers
function and drag it to the data-flow editor by using drag and drop.
3. Under the FL_## function category, select the global function
copyPerValue from your function library and drag it to the
data-flow editor by using drag and drop.
4. Select the SplitByValue function from the Node Functions area
and drag it to the data-flow editor by using drag and drop.
5. Connect the fields in the data-flow editor as follows: “custAddress
= SplitByValue(copyPerValue(getSuppliers(Supplier), Address))”.
6. Make sure that the context for the Supplier field is set to
POCombined.
f) Connect the target field items and the source field Supplier:
1. Drag the target field items and the source field Supplier to the
data-flow editor by using drag and drop.
2. Choose the User-Defined function category at the bottom of
the screen, select the assignItems function, and drag this to the
data-flow editor by using drag and drop.
3. Connect the fields in the data-flow editor as follows: items =
assignItems(Supplier).

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 125

Unit 3: Advanced Mapping Concepts BIT460

4. Make sure that the context for the Supplier field is set to
POCombined.
g) Connect the target field productNo and the source fields Supplier and
ProductID.
Drag the target field productNo and the source fields Supplier and
ProductID to the data-flow editor by using drag and drop.
h) Specify the functions to use in the message mapping:
1. Choose the assignSuppliers function from the User-Defined
function category and the SplitByValue function from the Node
Functions area and drag them to the data-flow editor by using
drag and drop.
2. Connect the fields in the data-flow editor as follows: productNo
= SplitByValue(assignSuppliers(Supplier,
ProductID)).
3. Make sure that the context for the Supplier and ProductId fields
is set to POCombined.
i) Connect the target field quantity and the source fields Supplier and
Quantity.
Drag the target field quantity and the source fields Supplier and
Quantity to the data-flow editor by using drag and drop.
j) Specify the functions to use in the message mapping:
1. Choose the assignSuppliers function from the User-Defined
function category and the SplitByValue function from the Node
Functions area and drag them to the data-flow editor by using
drag and drop.
2. Connect the fields in the data-flow editor as follows: quantity =
SplitByValue(assignSuppliers(Supplier, Quantity)).
3. Make sure that the context for the Supplier and Quantity fields
is set to POCombined.
k) Connect the target field price and the source fields Supplier and Price.
Drag the target field price and the source fields Supplier, and Price to
the data-flow editor by using drag and drop.
l) Specify the functions to use in the message mapping:
1. Choose the assignSuppliers function from the User-Defined
function category and the SplitByValue function from the Node
Functions area and drag them to the data-flow editor by using
drag and drop.

Continued on next page

126 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

2. Connect the fields in the data-flow editor as follows: “Price =

SplitByValue(assignSuppliers(Supplier, Price))”.
3. Make sure that the context for the Supplier and Price fields is
set to POCombined.
8. Test the mapping by using the mapping editor test function. For test
purposes, use a header and four details with two different Suppliers.
a) Display the Test tab page.
b) Create a new XML instance by choosing the Generate Instance icon.
c) To create additional structures, choose Duplicate Subtree in the context
menu for the Detail node. Create four structures for Detail.
d) Enter test values for the fields of the XML instance.
In the source document view, you can compare your instance with the
POCombined.xml file, or load the file as an XML instance.
e) Start the mapping program.
Choose Execute Mapping. The result should list the purchase orders for
OfficeMax and OfficeDepot separately. You can compare your result
with the POSplit.xml file.

2011 © 2011 SAP AG. All rights reserved. 127

Unit 3: Advanced Mapping Concepts BIT460

128 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

Exercise 10: Use variables in user-defined

functions
Exercise Objectives
After completing this exercise, you will be able to:
• use variables in user-defined functions

Business Example
You have to share data between different user-defined functions and need an easy
concept for this.

Task:
Define an attribute that can be used in all user-defined functions in a message
mapping.
Increment the value with each call of one of the user-defined functions, and write
the value to the trace.
1. Copy the message mapping OrderToSortedOrder to OrderToSorte-
dOrder_ext.
2. Define an attribute of type integer named counter.
3. Extend the existing user-defined functions so that each function call increases
the counter and writes the counter value as information to the trace.
4. Test the message mapping to check the counter values in the trace.

2011 © 2011 SAP AG. All rights reserved. 129

Unit 3: Advanced Mapping Concepts BIT460

Solution 10: Use variables in user-defined

functions
Task:
Define an attribute that can be used in all user-defined functions in a message
mapping.
Increment the value with each call of one of the user-defined functions, and write
the value to the trace.
1. Copy the message mapping OrderToSortedOrder to OrderToSorte-
dOrder_ext.
a) Select the message mapping OrderToSortedOrder.
b) Copy the message mapping.
Either open the object and choose Message Mapping / Copy Object ...,
or use the secondary mouse on the object in the browser section and
choose Copy Object ....
c) Name the new message mapping OrderToSortedOrder_ext and
choose Copy.
2. Define an attribute of type integer named counter.
a) Switch to edit mode in the message mapping.
b) Select the Functions tab.
c) Select the Java Area Attributes and Methods.
d) Add the following line to the Java Area:
int counter=0;
e) Save the message mapping.
f) Check the message mapping: choose F7.

Continued on next page

130 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with User-Defined Functions

3. Extend the existing user-defined functions so that each function call increases
the counter and writes the counter value as information to the trace.
a) Select the function getSuppliers to see the source code.
b) Increase the counter and write information to the trace.
Scroll down in the source code and add the following lines on the
bottom:
++counter;
AbstractTrace trace = container.getTrace();
trace.addInfo(counter + ". call (getSuppliers)");
c) Repeat steps a) and b) for the other user-defined functions.
Open the functions assignItems, and assignSupplier (one
after another). Enter the similar source code as above, just replace the
name of the function in bracket getSuppliers) with the respective
function name.
d) Save the message mapping.
e) Check the message mapping: choose F7.
4. Test the message mapping to check the counter values in the trace.
a) Select the Test tab.
b) Use the existing test data from the copied message mapping
OrderToSortedOrder
c) Ensure that the Trace Level is set to Info (at minimum).
d) Execute the test by choosing the Start the Transformationicon at the
bottom of the screen on the left.
The number of entries in the trace depends on your test data.

2011 © 2011 SAP AG. All rights reserved. 131

Unit 3: Advanced Mapping Concepts BIT460

Lesson Summary
You should now be able to:
• Create user-defined functions and use them in the mapping editor
• Define and use both local and global user-defined functions
• Create function libraries and include them in a message mapping
• Change queues and contexts using standard and user-defined functions
• Work with mapping objects
• Output messages in the trace log

132 © 2011 SAP AG. All rights reserved. 2011

BIT460 Unit Summary

Unit Summary
You should now be able to:
• Create a message mapping that makes use of contexts
• Set and delete the message-mapping context
• Use advanced options to help debug the message-mapping process
• Create user-defined functions and use them in the mapping editor
• Define and use both local and global user-defined functions
• Create function libraries and include them in a message mapping
• Change queues and contexts using standard and user-defined functions
• Work with mapping objects
• Output messages in the trace log

2011 © 2011 SAP AG. All rights reserved. 133

Unit Summary BIT460

134 © 2011 SAP AG. All rights reserved. 2011

 Unit 4
Advanced Functions

Unit Overview

Unit Objectives
After completing this unit, you will be able to:
• Define parameters for a mapping program
• Assign parameters to a mapping program at configuration time
• Use the term value mapping and therefore make use of advanced
message-mapping options
• Map multiple source and target messages
• Describe the procedure to use a multi-mapping in an interface determination
• Create mapping templates
• Use mapping templates in message mappings

Unit Contents
Lesson: Using Parameters in Mapping Programs ..........................136
Exercise 11: Create and Use Parameters in a Message Mapping...141
Lesson: Working with Value Mapping functions ............................147
Exercise 12: Use Value Mapping in a message mapping.............157
Exercise 13: Use RFC Lookup function .................................165
Lesson: Mapping Multiple Messages ........................................173
Lesson: Creating a Message-Mapping Template...........................178
Exercise 14: Create and Use a Mapping Template ....................181

2011 © 2011 SAP AG. All rights reserved. 135

Unit 4: Advanced Functions BIT460

Lesson: Using Parameters in Mapping Programs

Lesson Overview
This lesson explains how to assign parameters to mapping programs at
configuration time so that you can enable more applications to be used in a
mapping program.

Lesson Objectives
After completing this lesson, you will be able to:
• Define parameters for a mapping program
• Assign parameters to a mapping program at configuration time

Business Example
You have to define a graphical RFC lookup in a message mapping. So you need
to know how to define parameters in a message mapping, bind the message
mapping parameters to the operation mapping parameters, and set up the relevant
communication channel in the interface determination.

Message-Mapping Parameters
You can use parameters in mapping programs (for example, message mappings
and operation mappings). Using parameters in mapping programs means that you
do not have to specify values to be used in the mapping until configuration time.
Using parameters in a mapping program also improves reusability by enabling
the mapping program to be used in different operation mappings with different
parameter values.
In the mapping program, you define an interface that you can use to copy values to
(and query values from) the functions of a mapping program. The values may be
payload information transferred to the containers of an integration process. You
can use parameters to transfer the following values:
• Simple parameter values:
Simple values such as a separator for a concatenation function
• Dynamic parameter values:
Adapters for lookup functions to a mapping program.

136 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Parameters in Mapping Programs

Figure 41: Process for Parameterizing Mapping Programs

After you have defined parameters for your mapping program (MMP_1 and
MMP_2 in figure above), the mapping program is referenced in an operation
mapping. In the operation mapping, you also have to define relevant parameters
(OMP_1 and OMP_2 in the figure above) that you connect to the mapping-program
parameters using a binding. You must also set up a communication channel by
entering the operation mapping in an interface determination, for example, in
the Integration Directory. In the interface determination, you assign values to
the operation mapping parameters, which are then transferred to the mapping
program at runtime.
You can use parameters in the following mapping programs:

• Message Mappings
• Java Mapping
• XSLT Mapping
Note: Parameterized Mapping Programs cannot be used on the AEX
because it is not possible to specify parameters for the mapping program
in a Integrated Configuration, and an Interface Determination cannot
be used on AEX.

2011 © 2011 SAP AG. All rights reserved. 137

Unit 4: Advanced Functions BIT460

The Parameter-Definition Process

The following figures illustrate the implementation of parameters in a
message-mapping using the example of a message mapping to which a separator
for a concatenation function is to be transferred. The process involves the
following high-level steps:
1. Define parameters in the message mapping
2. Define parameters in the operation mapping and bind them to the
message-mapping parameters
3. Set the mapping parameters in the interface determination

Figure 42: Defining and Using Parameters in the Message Mapping

The parameters are defined on the Signature tab page of the message mapping.
Here, you name your parameters, specify whether they are simple type parameters
or adapters, and type the parameters. Once you have defined your parameters,
you can use them in your target-field mappings in the mapping editor. In the
example, the parameter MMP_Delimiter specifies the separator for the standard
function concat.

Hint: Parameters defined in the Signature are always import parameters.

(You can only transfer values of export parameters to integration processes
or monitoring processes).

138 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Parameters in Mapping Programs

Figure 43: Defining Parameters in the Operation Mapping and Binding

In the operation mapping in which the parameterized message mapping is

referenced, you can use the Definition tab page to create parameters. To access the
maintenance interface for operation mapping parameters, choose Parameters....
Using a binding, you can connect the operation mapping parameters to the
corresponding message mapping parameters.

2011 © 2011 SAP AG. All rights reserved. 139

Unit 4: Advanced Functions BIT460

Figure 44: Setting the Mapping Parameters in the Interface Determination

At the end of the parameter-definition process, you have to enter values for the
mapping parameters, for example, in an interface determination in the Integration
Directory in which the operation mapping is used.

Hint: If the parameters are not displayed in the lower screen area of
the interface determination for a parameterized operation mapping,
double-click the name of the operation mapping. The parameters are
then displayed.

140 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Parameters in Mapping Programs

Exercise 11: Create and Use Parameters

in a Message Mapping
Exercise Objectives
After completing this exercise, you will be able to:
• Create parameterized message mappings
• Execute binding for parameterized message mappings
• Assign values to the message-mapping interface in the Integration Directory

Business Example
You want to use an existing message mapping in a different context. However, this
context requires different values to be set for certain constants. For this reason,
you decide to use parameters in the message mapping so that you can set the
relevant constants in the Integration Directory according to the context.

Task:
You need to define a parameter for the existing message mapping MM_Cus-
tomerNameMerge in your namespace http://educationsap.com/pi/mapping## to
control which separator is set between the first and last names in the standard
function concat.
1. Open your message mapping.
In Enterprise Services Repository, navigate to your namespace
http://educationsap.com/pi/mapping## in software component version
SC_BIT_MAP, 1.0. Open your message mapping MM_CustomerNameMerge.
2. Create a message-mapping parameter.
Define an import parameter entitled MMP_Delimiter of type string. The
parameter should be of a simple type.
3. Define the operation-mapping parameter.
Display the operation mapping OM_CustomerInfoMap and create an import
parameter entitled OMP_Delimiter of type string. The parameter should
be of a simple type. Then bind the message mapping parameter to the
operation mapping parameter you just created.
4. Activate the interface-determination object.
Switch to the Integration Directory and choose your interface determination
object BC_CI_Requestor_## | CustomerInformation_Request | |Training.
Leave the parameter of the operation mapping OMP_Delimiter blank.
Activate your interface determination object.
5. Start the HTTP client and send a suitable request.

2011 © 2011 SAP AG. All rights reserved. 141

Unit 4: Advanced Functions BIT460

Solution 11: Create and Use Parameters in

a Message Mapping
Task:
You need to define a parameter for the existing message mapping MM_Cus-
tomerNameMerge in your namespace http://educationsap.com/pi/mapping## to
control which separator is set between the first and last names in the standard
function concat.
1. Open your message mapping.
In Enterprise Services Repository, navigate to your namespace
http://educationsap.com/pi/mapping## in software component version
SC_BIT_MAP, 1.0. Open your message mapping MM_CustomerNameMerge.
a) Logon to Enterprise Services Repository.
b) Open software component version node SC_BIT_MAP 1.0.
c) Navigate to your namespace.
Expand the namespace http://educationsap.com/pi/mapping##.
d) Open your message mapping.
Open the Message Mappings node and double-click
MM_CustomerNameMerge
2. Create a message-mapping parameter.

Continued on next page

142 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Parameters in Mapping Programs

Define an import parameter entitled MMP_Delimiter of type string. The

parameter should be of a simple type.
a) Specify the parameter properties.
Switch to edit mode and choose the Signature tab page. Enter the
following field values in the Parameters area:
Name: MMP_Delimiter
Category: Simple Type
Type: xsd:string
Parameter: Import
b) Include the newly created parameter in the message mapping.
1. Open the mapping editor by choosing the Definition tab page.
2. Double-click the standard function concat in the target-field
mapping for the MtName field.
3. In the dialog box that appears containing the separator options
available, use the input help to select the MMP_Delimiter
parameter you just created.
c) Save your message mapping.
3. Define the operation-mapping parameter.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 143

Unit 4: Advanced Functions BIT460

Display the operation mapping OM_CustomerInfoMap and create an import

parameter entitled OMP_Delimiter of type string. The parameter should
be of a simple type. Then bind the message mapping parameter to the
operation mapping parameter you just created.
a) Open the operation mapping.
Go to the Operation Mappings node and double-click
OM_CustomerInfoMap.
b) Specify the parameter properties.
Switch to change mode. In the Source Operation area, choose
Parameters.... Enter the following values in the specified fields:
Name: OMP_Delimiter
Category: Simple Type
Type: xsd:string
Parameter: Import
Then close the dialog box by choosing OK.
c) Bind the operation-mapping parameter.
Choose the pushbutton located in the Binding field in the Mapping
Program area. In the dialog box that opens, use the input help to
enter the operation mapping parameter OMP_DelimiterBinding in the
Binding field. Then close the popup by choosing Copy Object.
d) Save your operation mapping and activate both modified mapping
objects.
4. Activate the interface-determination object.

Continued on next page

144 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Using Parameters in Mapping Programs

Switch to the Integration Directory and choose your interface determination

object BC_CI_Requestor_## | CustomerInformation_Request | |Training.
Leave the parameter of the operation mapping OMP_Delimiter blank.
Activate your interface determination object.
a) Call the Integration Directory.
Go to the Process Integration Tools page and call the Integration
Directory by clicking Integration Builder link.
b) Edit your interface-determination object.
Open your interface-determination object BC_CI_Requestor_## |
CustomerInformation_Request | Training and switch to change mode.
c) Define the operation-mapping parameter.
The operation mapping parameter OMP_Delimiter is displayed at the
bottom of the screen (if it is not displayed, double-click the name of the
operation mapping). Leave the Value field blank by opening the field
help, clicking a constant, and selecting the blank entry.
d) Save and activate your interface determination.
5. Start the HTTP client and send a suitable request.
a) Start the HTTP client.
Starting the HTTP client simulates an application that generates an
XML document and then sends it to the SAP PI pipeline by using the
HTTP adapter. Set the details for the parameters so that they match
those for your scenario configuration (group number ##).
b) Send the request
To transfer the document to the pipeline, choose Send.
c) Check the status of the message.
Call transaction SXI_MONITOR on the Integration Server (client 800)
and check the processing of your messages in the message monitor.
The composite name on the output page of the request message should
be separated using a blank.

2011 © 2011 SAP AG. All rights reserved. 145

Unit 4: Advanced Functions BIT460

Lesson Summary
You should now be able to:
• Define parameters for a mapping program
• Assign parameters to a mapping program at configuration time

146 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with Value Mapping functions

Lesson: Working with Value Mapping functions

Lesson Overview
This lesson introduces the standard functions for value mapping.

Lesson Objectives
After completing this lesson, you will be able to:
• Use the term value mapping and therefore make use of advanced
message-mapping options

Business Example
You are responsible for the development of mappings in SAP NetWeaver Process
Integration and require an overview of the advanced message-mapping options
that value mappings provide.

Value Mapping as an Advanced Message-Mapping

Option
In some situations, senders and receivers know the same objects, but under
different names. This value transformation needs to be represented by a mapping
program. A simple solution is to use Boolean functions, but this can become
too complex.
A more elegant way of solving this task is to use value mappings or value-mapping
tables. In this case, the values you need to map are stored in a value-mapping
table and then read during the mapping.

FixValues
Value-mapping tables are maintained in the ES Repository
Value mapping
Value-mapping tables are maintained in the Integration Directory
Mapping lookups
Value-mapping tables are maintained in a back-end system
The standard function FixValues contains fixed value pairs in Enterprise Services
Repository, while the standard function Value mapping references value pairs
from the configuration. The mapping lookup accesses another system to request
the required values for the value mapping. This is explained in more detail in the
remainder of the lesson.

2011 © 2011 SAP AG. All rights reserved. 147

Unit 4: Advanced Functions BIT460

Value Mapping with Standard Function FixValues

The following figure shows how the standard function FixValues is used. FixValues
is a standard function of the Conversions function group; it enables fixed value
pairs to be saved in a message mapping (that is, in Enterprise Services Repository).

Figure 45: Value Mapping with the FixValues Standard Function

In the example, the source field CUSTTYPE is mapped to the target field
CUSTTYPE. The default value for the target field is “business”. However, if
the source field contains the values “B”, then the target field is given the value
“business_XX”. In a similar way, a source value “P” will be mapped to target
value “private_XX” .
Advantages and disadvantages of the standard function FixValues:
+ Easy to use
+ Possible to changes entries manually
+ Good runtime performance
- No mass upload of values
- Configuration values are in design
- Values only used in respective message mapping

Standard Function Value Mapping

Due to dependencies on customer-specific data, the actual values in a mapping are
often not known until configuration time. For this reason, the standard function
Value mapping gives you the option of referencing value-mapping tables, which
are saved in the Integration Directory.

148 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with Value Mapping functions

Enterprise Services Repository: Using Value Map-

ping in Message Mapping
The standard function Value Mapping is in the Conversions function group area
and you insert it between the source and target fields. You do not save the value
pairs for the conversion directly as the parameters of the function, but instead
specify key fields for accessing the value pairs (conversion values). The value
pairs themselves are saved in the configuration (in the Integration Directory),
using identical key fields (see below).
The following figure shows the required parameters for this function. The entries
in the value-mapping table must be assigned to a value-mapping context. This
context enables you to distinguish between value mappings from different areas.

Hint: Values that are manually maintained in the Integration Directory

automatically belong to the context http://sap.com/xi/XI. Alternatively,
you can replicate values from outside PI into PI with another context
by using an interface (see below).

The actual values are referenced with the key fields Agency and Scheme. These
key fields must be reused in the configuration.

Figure 46: Value Mapping Using the Standard Function Value Mapping

You can enter any strings for Agency and Scheme for the sender and receiver. It is
also possible to save a placeholder for the Agency field for the runtime constant
SenderParty or SenderService (and likewise for the receiver), which is replaced by
the current value during execution. The standard function Value mapping can be
used in different message mappings with the same key fields, thus referencing the
same “mapping table”.

2011 © 2011 SAP AG. All rights reserved. 149

Unit 4: Advanced Functions BIT460

Integration Directory: Populating a Value Mapping with Values

You create the value mapping tables in the Integration Directory. These values are
only valid for the context http://sap.com/xi/XI. Value-mapping groups are created
for semantically identical trios of values Agency, Scheme, and Value. The figure
Value-Mapping Groups in the Integration Directory shows an example with
the semantically identical values “B” and “business_xx”.

Figure 47: Value-Mapping Groups in the Integration Directory

A value-mapping group is an object (or instance) that is given different names in

different systems.
The mapping values in the value-mapping group have no direction: A
value-mapping group can be used in a message mapping with Value mapping
to generate the value “business_XX” from value “B”, and in another message
mapping to convert “business_XX” to “B”. You can also include further values
with other agency-scheme values if these represent the same object from a
business perspective.
Values that are to be converted to one another must be in the same value-mapping
group.

150 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with Value Mapping functions

To create conversion values in the Integration Directory, choose Tools →Value

Mapping. On the next screen, with Value Mapping Agencies selected, enter the
agencies and schemes for the sender and receiver as parameters.

Hint: To create a value-mapping group directly, in the Integration

Directory main menu, choose Object → New, and under Configuration
Objects, select the object type Value Mapping Group.

Value-mapping groups entered manually in the Integration Directory have the

advantage of being able to be versioned and transported (from the DEV to the
TEST system, for example).

Hint: If the mapping of the standard function Value mapping was not
executed, the message trace of the converted message contains the
following entry: Key mapping from ... has not been
performed. Check the key fields Agency and Scheme.

Figure 48: Value Mapping Overview

Advantages and disadvantages of the standard function Value Mapping:

+ Possible to change entries manually (not in replication, see below)
+ Good runtime performance
+ Configuration values are in the Integration Directory

2011 © 2011 SAP AG. All rights reserved. 151

Unit 4: Advanced Functions BIT460

+ Possible to use values from different message mappings

+ Possible to use Java and XSLT mappings
+ Possible to transport values (DEV to TEST)
+ In replication: Possible to use values from the back end
- Takes time to learn
- Mass upload of values only possible using replication (see below)

Populating a Value Mapping with Values by Us-

ing a Service Interface
To replicate value-mapping data from other applications in the runtime cache
(on the Integration Server), you can use service interfaces (“value-mapping
replication interfaces”). The interfaces enable you to realize both synchronous
and asynchronous replication scenarios. You can also use these interfaces to
automatically create value-mapping groups for mass data.
The value-mapping replication interfaces are included in the SAP NetWeaver
PI shipment and are located in software component version SAP BASIS →
SAP BASIS 7.30 in the namespace http://sap.com/xi/XI/System. There are four
interfaces in total; two synchronous and two asynchronous, or two outbound
and two inbound. The AS Java offers inbound proxies for the inbound service
interfaces. The AS ABAP offers outbound proxies for the outbound interfaces in
the basis (in the ABAP stack of the Integration Server, as in every ABAP system
based on Basis 6.40 and above).

Service Interfaces for Value Mapping Replication

Name Mode Direction Imple-
mentation
ValueMappingReplication Async. Inbound Java
ValueMappingReplicationOut Async. Outbound ABAP
ValueMappingReplicationSynchronous Sync. Inbound Java
ValueMappingReplicationOutSynchronous Sync. Outbound ABAP

Hint: The disadvantage of this replication method is that the

value-mapping tables cannot be called in the Integration Directory
because the original versions of the runtime data are located in the filling
application.

152 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with Value Mapping functions

Configuration for Value-Mapping Replication

The target of the value mapping values is the PI system's Java stack. The
prerequisites are:
• Create business system for the PI Java stack
In SLD (type AS Java), import to Integration Directory
• Create communication channel (XI receiver)
URL points to http://<pi-host>:<java-port>/MessagingSystem/re-
ceive/JPR/XI
• Register Java inbound proxy
See http://<pi-host>:<java-port>/ProxyServer/
• Create routing configuration
From sender to business system of PI Java stack
The sender can be any system containing values for value mapping. If it is an
ABAP system (with proxy runtime), you can use the ABAP outbound interfaces
that are already implemented as ABAP proxies to transfer the data. The sender
interface can be any other interface containing the required information. You must
also create a mapping (from the sender interface to the ValueMappingReplication
interface).

Mapping Lookups
Mapping lookups access values (tables) in a back-end system during mapping
runtime. The lookup can be executed using the standard functions RFC Lookup or
JDBC Lookup (see below), or using the lookup API from java coding.

Note: The lookup API can be used either in a user-defined function in a

message mapping, or in Java or XSLT mappings.

The lookup API provides methods for generic access to application systems using
the RFC, JDBC, and SOAP adapter. There is also a special API for the JDBC
adapter that simplifies access.
The Java program transfers a payload stream to the API, which the Adapter
Engine uses to send synchronously to the target system (but not a complete PI
message with message header). To deliver to the target system, a communication
channel must have been set up in the Integration Directory. The response to this
synchronous request is received as a stream by the Java program and must be
parsed. For more information about these APIs, see the SAP Developer Network
at https://www.sdn.sap.com/irj/sdn/javadocs (you will need an SDN user).
If the configuration is complete and runtime is active, you can test lookups as part
of a mapping program by using the test environment of an operation mapping.

2011 © 2011 SAP AG. All rights reserved. 153

Unit 4: Advanced Functions BIT460

Figure 49: Mapping Lookups

The mapping editor includes standard functions RFC Lookup and JDBC Lookup
that you can use to graphically define a mapping lookup using either the RFC
adapter or the JDBC adapter.
RFC Lookup takes into account the request, response, and fault parts of an
imported RFC-Signature. To be able to model the lookup graphically, the structure
of the RFC interface must be known. To use this structure in the mapping editor,
you have to import the RFC-Signature into Enterprise Services Repository. In the
figure below, an RFC lookup is used in a target-field mapping to obtain additional
information about the number of available seats on a flight from an SAP system
at runtime. Function module Z_BIT_MAP_GET_FREE_SEATS is used for this
purpose. This uses the input parameters (aircraft type and number of occupied
seats) to return the number of available seats.

154 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with Value Mapping functions

Figure 50: Standard function RFC Lookup in the Mapping Editor

Advantages and disadvantages of mapping lookups:

+ Configuration values are in the back-end system
+ Possible to use values from different mappings
+ Graphical support for RFC and JDBC
– Takes time to learn (programming) when the standard graphical functions
(RFC and JDBC) are not used
– Runtime performance issues

2011 © 2011 SAP AG. All rights reserved. 155

Unit 4: Advanced Functions BIT460

156 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with Value Mapping functions

Exercise 12: Use Value Mapping in a

message mapping
Exercise Objectives
After completing this exercise, you will be able to:
• Use the standard function Value Mapping in message mapping
• Enter conversion values for the value mapping
• Check the value-mapping groups

Business Example
Your company uses different values to represent customer types. You want a
conversion to take place in the PI mapping you have created. To do this, you use
the standard function Value Mapping.

Task 1: (Design) Use Standard Function Value

Mapping in Enterprise Services Repository
Use the standard function Value Mapping to enable conversion between different
representations of the customer type (CUSTTYPE) field.
1. In your operation mapping OM_CustomerInfoMap, reference a message
mapping MM_CustomerInfo as the mapping program for the response and
create this message mapping from the operation mapping.
2. Map all fields with the same name.
3. For the CUSTTYPE target field, insert the standard function Value Mapping
and save the following parameters:

Parameters for Standard Function Value Mapping

Context http://sap.com/xi/XI
Agency SenderService
Scheme S_CUSTTYPE_##
Agency ReceiverService
Scheme CustType_##
Behaviour if Lookup Fails Use Key

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 157

Unit 4: Advanced Functions BIT460

Task 2: (Configuration) Create Value Mapping Groups

in the Integration Directory.
Create Value Mapping Groups and enter the conversion values.
1. Create a Value Mapping Group named VMG_business_customer_##.
Maintain the value mapping between value “B” (for Service Training,
Scheme S_CUSTTYPE_##) and value “business_customer_##” (for Service
BC_CI_Requestor_##, Scheme CustType_##).

Hint: To avoid conflicts while editing the value mapping groups, the
schema were set group-specific so that every participant can work
on group specific objects.

2. Create a Value Mapping Group named VMG_private_customer_##.

Maintain the value mapping between value “P” (for Service Training,
Scheme S_CUSTTYPE_##) and value “private_customer_##” (for Service
BC_CI_Requestor_##, Scheme CustType_##).

Task 3: (Optional Monitoring) Check Value-Mapping

Groups in Cache Monitoring in the Runtime Workbench
Check the value-mapping groups in cache monitoring in the Runtime Workbench.
1. Navigate to the Cache Monitoring of the value-mapping groups in the
Runtime Workbench.
2. Display the value-mapping for your sender system BC_CI_Requestor_##.

Task 4: (Runtime) Check Execution of the Value

Mapping Using a Test Message
Use a test message to check whether the Value Mapping is executed.
1. Start the HTTP client and send a suitable request. Check the field content for
the CUSTTYPE field in the response.

158 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with Value Mapping functions

Solution 12: Use Value Mapping in a

message mapping
Task 1: (Design) Use Standard Function Value
Mapping in Enterprise Services Repository
Use the standard function Value Mapping to enable conversion between different
representations of the customer type (CUSTTYPE) field.
1. In your operation mapping OM_CustomerInfoMap, reference a message
mapping MM_CustomerInfo as the mapping program for the response and
create this message mapping from the operation mapping.
a) Open the operation mapping.
In the objects for your namespace http://educationsap.com/pi/map-
ping##, navigate to the Operation Mappings node and double-click the
operation mapping OM_CustomerInfoMap to open it.
b) Reference message mapping for response.
Switch to change mode, select the Response tab page
and enter the name MM_CustomerInfo and namespace
http://educationsap.com/pi/mapping## as the mapping program (of
type Message Mapping).
c) Create message mapping for response.
To create the message mapping, try to open the object by
double-clicking the name MM_CustomerInfo (or, in the context
menu, choose Subobject → New). Answer the question “Do you want
to create the object MM_CustomerInfo?” with Create and confirm again
on the following screen by choosing Create.
2. Map all fields with the same name.
a) Select both root structures.
In both structures, select the root structure MtCustomerInfo.
b) Apply auto-field mapping.
Use the function “Map Selected Fields and Substructures if Names
Are Identical” (second pushbutton from the left at the top of “Design”
tab page) to map all fields.
3. For the CUSTTYPE target field, insert the standard function Value Mapping
and save the following parameters:

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 159

Unit 4: Advanced Functions BIT460

Parameters for Standard Function Value Mapping

Context http://sap.com/xi/XI
Agency SenderService
Scheme S_CUSTTYPE_##
Agency ReceiverService
Scheme CustType_##
Behaviour if Lookup Fails Use Key

a) Open the mapping for CUSTTYPE.

To see the mapping so far in the data-flow editor, double-click the
CUSTTYPE target field.
b) Remove the existing mapping.
Remove the arrow from the CUSTTYPE target field.
c) Add the Value Mapping standard function.
In the Functions area in the footer of the data-flow editor, select the
Conversions category and use drag and drop to drag the Value Mapping
function into the data-flow editor.
d) Connect source and target fields to the Value Mapping.
Connect the outbound field of the CUSTTYPE source field with the
inbound field of the Value Mapping standard function. Connect the
outbound field of the Value Mapping standard function with the
inbound field of the CUSTTYPE source field.
e) Maintain the parameters for the Value mapping.
Double-click the Value mapping standard function and maintain the
values as listed in the table above. Choose OK to close the window.
f) Save and activate all objects.

Continued on next page

160 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with Value Mapping functions

Task 2: (Configuration) Create Value Mapping Groups

in the Integration Directory.
Create Value Mapping Groups and enter the conversion values.
1. Create a Value Mapping Group named VMG_business_customer_##.
Maintain the value mapping between value “B” (for Service Training,
Scheme S_CUSTTYPE_##) and value “business_customer_##” (for Service
BC_CI_Requestor_##, Scheme CustType_##).

Hint: To avoid conflicts while editing the value mapping groups, the
schema were set group-specific so that every participant can work
on group specific objects.

a) Create a new Value Mapping Group.

In the Integration Directory, choose Object -> New -> Configuration
Objects -> Value Mapping Group. Specify the name as
VMG_business_customer_## and choose Create to create the group.
b) Enter the values as given in the table:

Value-Mapping-Group VMG_business_customer_##
Agency Scheme Value
BC_CI_Re- CustType_## business_##
questor_##
Training S_CUSTTYPE_## B

Hint: For the Agency, you may use the drop-down menu to
select Business System and then select the system from the list
of available systems.

c) Save the value mapping group.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 161

Unit 4: Advanced Functions BIT460

2. Create a Value Mapping Group named VMG_private_customer_##.

Maintain the value mapping between value “P” (for Service Training,
Scheme S_CUSTTYPE_##) and value “private_customer_##” (for Service
BC_CI_Requestor_##, Scheme CustType_##).
a) Create a new Value Mapping Group.
In the Integration Directory, choose Object -> New -> Configuration
Objects -> Value Mapping Group. Specify the name as
VMG_private_customer_## and choose Create to create the group.
b) Enter the values as given in the table:

Value-Mapping-Group VMG_private_customer_##
Agency Scheme Value
BC_CI_Re- CustType_## private_##
questor_##
Training S_CUSTTYPE_## P

Hint: Since the values for the Schema are the same as for the
first value mapping group, you may now use the input help for
Scheme for the values to be listed .

c) Save and activate both value mapping groups.

Task 3: (Optional Monitoring) Check Value-Mapping

Groups in Cache Monitoring in the Runtime Workbench
Check the value-mapping groups in cache monitoring in the Runtime Workbench.
1. Navigate to the Cache Monitoring of the value-mapping groups in the
Runtime Workbench.
a) Open the Runtime Workbench.
You can call the Runtime Workbench from the Process Integration
Tools page, for example. Alternatively, you can use the URL
http://<PI-Host>:<HTTP-Port>/rwb.
b) Choose Cache Monitoring.
c) Select Cache Instance Mapping Runtime Cache (Central Adapter
Engine).
d) Select Cache Object value-mapping groups.

Continued on next page

162 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with Value Mapping functions

2. Display the value-mapping for your sender system BC_CI_Requestor_##.

a) Leave the context as http://sap.com/xi/XI and use the button Input Help
for Agency to select your sender system BC_CI_Requestor_##.
b) Choose Search for a list of the value-mappings.

Hint: The name of the value-mapping group is not displayed.

Task 4: (Runtime) Check Execution of the Value

Mapping Using a Test Message
Use a test message to check whether the Value Mapping is executed.
1. Start the HTTP client and send a suitable request. Check the field content for
the CUSTTYPE field in the response.
a) Start the HTTP client.
Open the HTTP client from the file share. Your instructor will tell you
where to find the file. Set the details for the parameters so that they
match those for your scenario configuration (group number ##).
b) To transfer the document to the pipeline, choose Send.
c) Check in the form in the last text area at the bottom of the response
whether the conversion for the CUSTTYPE field has been executed.

2011 © 2011 SAP AG. All rights reserved. 163

Unit 4: Advanced Functions BIT460

164 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with Value Mapping functions

Exercise 13: Use RFC Lookup function

Exercise Objectives
After completing this exercise, you will be able to:
• use RFC lookup standard function in a message mapping
• configure a scenario to use an adapter for the RFC lookup

Business Example
In a message mapping, you want to use a value-mapping-table located in an
ABAP back-end system.

Task 1: Use RFC Lookup standard function in a

message mapping
Use the standard function RFC Lookup in your message mapping
MM_CustomerInfo to call the remote-enabled function module
Z_RFM_DEMO_RFC_LOOKUP in Business System Training for the mapping
of the source and target field CUSTTYPE.
1. Open your message mapping MM_CustomerInfo in edit mode.
2. Maintain a parameter named MMP_RFC_CC of category Adapter and type
RFC (Parameter import) for the message mapping.
3. Add the standard function RFC Lookup to the target field mapping of
CUSTTYPE.
4. Maintain the attributes for the RFC Lookup.
5. Save and test the message mapping.

Task 2: Use binding in Operation Mapping for

parameter of type Adapter
Modify your operation mapping OM_CustomerInfoMap to use the modified
message mapping MM_CustomerInfo with the parameter and maintain a value
for that parameter in the interface determination.
1. Open your operation mapping OM_CustomerInfoMap in edit mode.
2. Add a parameter named OMP_CC of type Adapter RFC
3. Bind that parameter OMP_CC to the parameter of the message mapping
MM_CustomerInfo.
4. Save and activate the operation mapping as well as the message mapping.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 165

Unit 4: Advanced Functions BIT460

5. Set the name for the communication channel to Training_RFC_In for the in-
terface determination BC_CI_Requestor_## | CustomerInformation_Request
| | Training.
6. Save and activate the interface determination BC_CI_Requestor_## |
CustomerInformation_Request | | Training.

Task 3: Test scenario using RFC lookup

Test your scenario with the HTTP client to check if the RFC lookup executes.
1. Open the HTTP client.
2. Send a request.
3. Check the response.

166 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with Value Mapping functions

Solution 13: Use RFC Lookup function

Task 1: Use RFC Lookup standard function in a
message mapping
Use the standard function RFC Lookup in your message mapping
MM_CustomerInfo to call the remote-enabled function module
Z_RFM_DEMO_RFC_LOOKUP in Business System Training for the mapping
of the source and target field CUSTTYPE.
1. Open your message mapping MM_CustomerInfo in edit mode.
a) Open SWCV SC_BIT_MAP 1.0, therein your namespace
http://educationsap.com/pi/mapping##, and open the node Message
Mappings.
b) Open your message mapping MM_CustomerInfo with a double-click.
c) Switch to edit mode.
2. Maintain a parameter named MMP_RFC_CC of category Adapter and type
RFC (Parameter import) for the message mapping.
a) Open the Signature tab.
b) Maintain a parameter named MMP_RFC_CC.
In the section Parameters below, in the existing line, click in the field
Name and enter MMP_RFC_CC.
c) Click enter: the other fields are filled.
d) Change the Category to Adapter.
Change the Category from Simple Type to Adapter by selecting the
Category field and using the drop-down menu.
e) Set the Type to RFC.
Use the input help to choose Adapter Metadata. Select the Name RFC
(Software Component Version SAP BASIS 7.30). Click Apply to close
the popup.
f) Keep the Parameter as Import parameter.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 167

Unit 4: Advanced Functions BIT460

3. Add the standard function RFC Lookup to the target field mapping of
CUSTTYPE.
a) Open the Definition tab.
b) Open the field mapping for the target field CUSTTYPE.
Double-click the field CUSTTYPE from the target structure
MtCustomerInfo.
c) Add the standard function RFC Lookup
Select the functions category Conversions and drag the function RFC
Lookup to the flow editor.

Hint: In case the field mapping contains the function Value

mapping, delete this Value mapping.

4. Maintain the attributes for the RFC Lookup.

a) Double-click the function RFC Lookup to open the maintenance view
for the parameters.
b) Maintain the parameter MMP_RFC_CC.
In the drop-down menu for Communication Channel, select the
parameter MMP_RFC_CC.
c) Maintain the function module Z_RFM_DEMO_RFC_LOOKUP.
Use the input help near the text “Select an RFC module”. In
the popup, select the remote-enabled function module (RFM)
Z_RFM_DEMO_RFC_LOOKUP. Click Apply to close the popup.
d) Add the import and the export parameter to the function signature.
Open the import and export structure of the RFM by clicking on
the little triangles in front of Z_RFM_DEMO_RFC_LOOKUP and
Z_RFM_DEMO_RFC_LOOKUP.Response.
On the left-hand, select the parameter I_CUST_TYPE and double-click
it to add it to the table below. On the right-hand, select the parameter
E_CUSTOMER_TYPE and double-click it to add it to the table below.
e) Close the RFC Lookup maintenance window: Click OK.
f) Connect the source and target fields CUSTTYPE to the input and
output fields of the function RFC Lookup.

Continued on next page

168 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with Value Mapping functions

5. Save and test the message mapping.

a) Save the message mapping.
b) Use the tab Test to navigate to the test section.
c) Maintain parameters for the payload.
Set the value of the CUSTTYPE field to either B or P (in upper case!).
Maintain the other fields with arbitrary values.
d) Specify the communication channel for parameter MMP_RFC_CC.
Select the tab Parameters below the input structure. In the parameters
section upper part, the Import Parameter MMP_RFC_CC is listed. Use
the input help to select the communication channel Training_RFC_In
for Communication Component Training. Click Apply to close the
Communication Channel selection window.
e) Execute the test to check if the CUSTTYPE field is converted to lower
case.
Execute the test by choosing the Start Transformation icon at the
bottom of the screen on the left. Check the Result: open the structure
MtCustomerInfo to see if the value for the CUSTTYPE field has been
converted to lower case.

Hint: Do not activate the message mapping now: it is

referenced in an operation mapping that does not (yet) supply
the name of the communication channel as parameter.

Task 2: Use binding in Operation Mapping for

parameter of type Adapter
Modify your operation mapping OM_CustomerInfoMap to use the modified
message mapping MM_CustomerInfo with the parameter and maintain a value
for that parameter in the interface determination.
1. Open your operation mapping OM_CustomerInfoMap in edit mode.
a) Open the operation mapping.
In your namespace http://educationsap.com/pi/mapping##, navigate
to the Operation Mappings node and open the operation mapping
OM_CustomerInfoMap by double-clicking it.
b) Switch to edit mode.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 169

Unit 4: Advanced Functions BIT460

2. Add a parameter named OMP_CC of type Adapter RFC

a) Open the parameters list.
Use the button Parameters for a list of parameters to be displayed
below the Request / Response / Fault section.
b) Add a parameter named OMP_CC.
In the empty entry field for Name, enter OMP_CC.
c) Press enter for the other fields to be filled.
d) Change the Category to Adapter.
Change the Category from Simple Type to Adapter by selecting the
Category field and using the drop-down menu.
e) Set the Type to RFC.
Use the input help to choose Adapter Metadata. Select the Name RFC
(Software Component Version SAP BASIS 7.30). Click Apply to close
the popup.
f) Keep the Parameter as Import parameter.
3. Bind that parameter OMP_CC to the parameter of the message mapping
MM_CustomerInfo.
a) Switch to the Response tab.
b) Create the binding.
In the line for the Mapping Program MM_CustomerInfo, choose the
button below Binding. In the popup, select the field with the question
mark below Binding to select the parameter OMP_CC. Click OK to
close the popup.
4. Save and activate the operation mapping as well as the message mapping.
a) Save the operation mapping.
b) Choose the menu option Operation Mapping / Activate.
c) In the Change list popup, select both the operation mapping as well
as the message mapping.
d) Click Activate to activate the objects.

Continued on next page

170 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Working with Value Mapping functions

5. Set the name for the communication channel to Training_RFC_In for the in-
terface determination BC_CI_Requestor_## | CustomerInformation_Request
| | Training.
a) Open the Integration Directory.
b) Open the interface determination BC_CI_Requestor_## |
CustomerInformation_Request | | Training.
c) Switch to edit mode.
d) Click the line with the operation mapping OM_CustomerInfoMap
for the parameters to be displayed.
e) Below, click the question mark below Value and open the input
help. Select the communication channel Training_RFC_In for
Communication Component Training. Click Apply to close the
Communication Channel selection window.
6. Save and activate the interface determination BC_CI_Requestor_## |
CustomerInformation_Request | | Training.
a) Save the interface determination.
b) Activate the interface determination using the menu Interface
Determination / Activate.

Task 3: Test scenario using RFC lookup

Test your scenario with the HTTP client to check if the RFC lookup executes.
1. Open the HTTP client.
a) Open the HTTP client from the file share. Your instructor will tell you
where to find the file.
b) Maintain your group number.
2. Send a request.
a) Transfer the document to the pipeline; choose Send.
3. Check the response.
a) Call transaction SXI_MONITOR on the Integration Server (client 800)
and check the processing of your messages in the message monitor

2011 © 2011 SAP AG. All rights reserved. 171

Unit 4: Advanced Functions BIT460

Lesson Summary
You should now be able to:
• Use the term value mapping and therefore make use of advanced
message-mapping options

172 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Mapping Multiple Messages

Lesson: Mapping Multiple Messages

Lesson Overview
This lesson explains the concept of multi-mapping by showing how to map
multiple source and target messages. The lesson also shows how to reference
multi-mapping for the purposes of a receiver determination or an interface
determination.

Lesson Objectives
After completing this lesson, you will be able to:
• Map multiple source and target messages
• Describe the procedure to use a multi-mapping in an interface determination

Business Example
You are responsible for the development of mappings in SAP NetWeaver Process
Integration and need to understand how to use the advanced message mapping
options that multi-mapping provide.

Multi-Mapping Configurations
Traditionally, mapping programs were used to create 1:1 mappings between
source and target messages. However, there are scenarios in which it is necessary
to process multiple messages. For example, an integration process (ccBPM) might
be designed to wait for multiple messages to arrive before processing all messages
and sending them to a receiver.
The actual multi-mapping is created in the mapping editor.

Hint: Provided the required schemas are available, you can also create
a multi-mapping in Java mappings, for example, by exporting the data
from Enterprise Services Repository.

2011 © 2011 SAP AG. All rights reserved. 173

Unit 4: Advanced Functions BIT460

The following multi-mapping options are available:

• n:1 mapping:
Multiple messages are combined into one message (for example, multiple
purchase orders are combined to make just single purchase order).
• 1:n mapping:
One large message is split into multiple individual messages (for example,
one large purchase order is divided into the individual purchase order items).
• n:m mapping:
n source messages are transformed into m target messages.

The Multi-Mapping Message Structure

Multi-mappings reference multiple message structures. All source messages are
put in one source structure and all target messages are put in one target structure.
For this reason, technically speaking, the mapping program is executed between a
source structure and a target structure.
The concept of multi-mappings is illustrated in the figure Example of an n:m
Multi-Mapping.

Figure 51: Example of an n:m Multi-Mapping

The mapping program creates the values of the target message types Order and
OrderInfo from the values of the message types OrderHeader and OrderItem. In
this case, only an n:2 multi-mapping is executed. On both sides, the message types

174 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Mapping Multiple Messages

are under the root element Messages (the name cannot be changed) and under the
elements Message1 and Message2. The sequence is specified by the configuration
in the message editor.
The figure Configuration of an n:m Multi-Mapping in the Mapping Editor
shows the procedure in the mapping editor.

Figure 52: Configuration of an n:m Multi-Mapping in the Mapping Editor

Depending on the sequence of the inserted message types in the input field on the
Signature tab page, the messages will also be made available in the structure
overview on the Definition tab page. In the next step, you define the mapping
program in the data flow editor.
The following restriction applies for the source and target messages that you
reference from a message mapping: The source and target messages can be in a
different software component version (SWCV) to the message mapping, but they
must both originate from the same SWCV (and, if applicable, underlying SWCV).

Using Multi-Mapping in an Interface Determination

You may reference a multi-mapping in an interface determination.
The operation mapping used in the interface determination must reference an
(1:n) multi-mapping program, which ensures that a single message is split into
individual messages in a message split.

2011 © 2011 SAP AG. All rights reserved. 175

Unit 4: Advanced Functions BIT460

For example, if the mapping program contains sub structures (or fields) with an
occurrence of 0 ... unbounded and one message is to be created for each instance,
you can use a multi-mapping to create individual messages. These individual
messages are initially bundled into one bulk message. The bulk message is then
transferred to the Adapter Engine where it is split up into the individual messages
again as illustrated in the following figure.

Figure 53: Bulk Message in an Interface Determination with multiple receiver

interfaces

Both the bulk message and the individual messages have a message header with
a receiver interface that is defined by the mapping, and which may be different
for each individual message.

Hint: For a mapping-based message split, the messages must all be sent
by using the same Adapter Engine. Attachments from the original message
are not transferred to the messages that are created in the message split.

Hint: The AEX (Advanced Adapter Engine Extended) is able to use a

mapping-based message split in an interface determination.

176 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Mapping Multiple Messages

Lesson Summary
You should now be able to:
• Map multiple source and target messages
• Describe the procedure to use a multi-mapping in an interface determination

2011 © 2011 SAP AG. All rights reserved. 177

Unit 4: Advanced Functions BIT460

Lesson: Creating a Message-Mapping Template

Lesson Overview
This lesson shows you how to create a message-mapping template and explains
the message-mapping options that a mapping template provides.

Lesson Objectives
After completing this lesson, you will be able to:
• Create mapping templates
• Use mapping templates in message mappings

Business Example
You have repetitive mapping tasks that you want to perform with the aid of a
single mapping, which you can use as required for multiple substructures.

The Message-Mapping Template

In the same way that you reuse data types in different message types, you can also
save and reuse parts of message mappings as mapping templates. A mapping
template serves as a basic predefined unit that you can load into (and use in) other
message mappings and then adjust to meet your requirements.
You can create mapping templates for structure mappings for the following types:

• Data types
• Complex types extracted from IDoc structures and RFC function headers
• Complex types in external definitions

Hint: You can also use a mapping template for an individual field provided
that the field references a simple data type (and not a XSD data type).

The data types referenced by mapping templates can exist in any software
component versions.
The following figure illustrates how you can define a mapping template and how
you can use existing mapping templates.

178 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Message-Mapping Template

Figure 54: Using Mapping Templates

In a message mapping, you can display which mapping templates have already
been referenced. Furthermore, if structures are selected in the source and target
structures, you can also display or create appropriate mapping templates.

Hint: A user-defined function is also copied to a mapping template if the

user-defined function is used for fields that are part of a structure used
for the mapping template.

If a mapping template is modified after it has been referenced, the change is not
automatically transferred to the message mapping in which the mapping template
is referenced.

2011 © 2011 SAP AG. All rights reserved. 179

Unit 4: Advanced Functions BIT460

180 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Message-Mapping Template

Exercise 14: Create and Use a Mapping

Template
Exercise Objectives
After completing this exercise, you will be able to:
• Create and use mapping templates in a message mapping

Business Example
A specific mapping task requires you to use mapping templates in a message
mapping.

Task:
You want to use a mapping template in a message mapping that maps the message
types Contact and Customer. The message type Contact comprises the data
types Name and Address; the message type Customer comprises the data types
CustName and CustomerAddress.
1. Start Enterprise Services Repository.
Navigate to your namespace http://educationsap.com/pi/mapping## in
software component version SC_BIT_MAP, 1.0.
2. Create a message-mapping template.
In your http://educationsap.com/pi/mapping## namespace, create a mapping
template with the name NameToCustName. Use the data types Name and
CustName (both from SWCV SC_BIT_MAP, 1.0 under Basis Objects in
namespace urn:educationsap.com:bit:mapping). Assign the Gender target
field to the Title source field. The source fields Firstname and Surname are to
be linked with a blank and transferred to the target field Name.

Note: To select the source or target structure, select the relevant data
type from the navigation tree and link it to the appropriate fields for
the structures by using drag and drop.

3. Test the mapping template.

4. Create a message mapping with the name ContactToCustomer.
In the message mapping, reference the message type Contact as the source
structure and the message type Customer as the target structure.
5. Connect source and target fields.
6. Choose the message-mapping template.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 181

Unit 4: Advanced Functions BIT460

Select the mapping template NameToCustName as the message-mapping

template in the mapping editor between the Name and CustomerName
structures.
7. Connect the address fields in the source and target structures.
Connect the fields with the same name in the Address and CustomerAddress
structures.
8. Create another message-mapping template.
Create an additional message-mapping template, this time with the
name AddressToAddress, between the data types Address and
CustomerAddress. An identical mapping is required between the source and
target fields Street, ZIPCode, and City.
9. Save the ContactToCustomer message mapping and display the mapping
templates used.
10. Test the mapping by using the mapping editor test function.

182 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Message-Mapping Template

Solution 14: Create and Use a Mapping

Template
Task:
You want to use a mapping template in a message mapping that maps the message
types Contact and Customer. The message type Contact comprises the data
types Name and Address; the message type Customer comprises the data types
CustName and CustomerAddress.
1. Start Enterprise Services Repository.
Navigate to your namespace http://educationsap.com/pi/mapping## in
software component version SC_BIT_MAP, 1.0.
a) Choose the Enterprise Services Builder link from the PI Tools
Homepage.
b) Navigate to your namespace.
Expand the software component version SC_BIT_MAP, 1.0 followed
by your namespace http://educationsap.com/pi/mapping##.
2. Create a message-mapping template.
In your http://educationsap.com/pi/mapping## namespace, create a mapping
template with the name NameToCustName. Use the data types Name and
CustName (both from SWCV SC_BIT_MAP, 1.0 under Basis Objects in

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 183

Unit 4: Advanced Functions BIT460

namespace urn:educationsap.com:bit:mapping). Assign the Gender target

field to the Title source field. The source fields Firstname and Surname are to
be linked with a blank and transferred to the target field Name.

Note: To select the source or target structure, select the relevant data
type from the navigation tree and link it to the appropriate fields for
the structures by using drag and drop.

a) Create a mapping template.

Go to the objects for your namespace http://educationsap.com/pi/map-
ping##. To create a new mapping template, call the context menu and
choose New → Mapping Objects → Mapping Template. Enter the
name NameToCustName and choose Create.
b) Select the source and target data types.
1. In SWCV SC_BIT_MAP, 1.0, choose Basis Objects →
urn:educationsap.com:bit:mapping → Interface Objects → Data
Types.
2. Using drag and drop, drag the Name data type to the Select a
Source Type field.
3. Using drag and drop, drag the CustName data type to the Select a
Target Type field.
c) Connect source and target fields.
1. Drag the Gender target field to the Title source field.
2. Drag the Name target field to the data flow editor, followed by
the Firstname and Surname source fields, and finally the concat
standard function (from the Text function category).
3. Drag a connecting line from the source field of Firstname to
the top-left concat inbound field, and from the source field of
Surname to the bottom-left concat inbound field.
4. Drag a connecting line from the source field of concat to the
Name inbound field.
d) Specify the function to use.
Choose the concat function and enter a blank as a delimiter to separate
the fields.
e) Save your changes.
Choose Apply to leave the screen for maintaining the properties of the
concat step.

Continued on next page

184 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Message-Mapping Template

3. Test the mapping template.

a) Choose the Test tab page and create a new XML instance by choosing
Generate Instance.
b) Expand the nodes in the XML instance and populate the fields with
test values.
c) Start the mapping-template test by choosing Execute Mapping.
4. Create a message mapping with the name ContactToCustomer.
In the message mapping, reference the message type Contact as the source
structure and the message type Customer as the target structure.
a) Create the new message mapping.
1. Display the objects for your namespace http://education-
sap.com/pi/mapping##.
2. To create a new message mapping, choose New → Mapping
Objects → Message Mapping in the context menu.
3. Enter the name ContactToCustomer and your namespace
and choose Create and enter a description.
b) Specify the source message type.
Using drag and drop, drag the Contact message type to the Select a
Source Type field.
c) Specify the target message type.
Using drag and drop, drag the Customer message type to the Select
a Target Type field.
5. Connect source and target fields.
a) Connect the CustID field of the target structure to the Ref field of the
source structure.
b) Drag the CustID field of the target structure to the Ref field of the
source structure using drag and drop.
6. Choose the message-mapping template.
Select the mapping template NameToCustName as the message-mapping
template in the mapping editor between the Name and CustomerName
structures.
a) Select the Name and CustomerName structures.
b) Either call the context menu for the CustomerName structure and choose
Show Suitable Templates, or choose the Show Suitable Templates icon.
c) Select the message-mapping template NameToCustName.
Continued on next page

2011 © 2011 SAP AG. All rights reserved. 185

Unit 4: Advanced Functions BIT460

7. Connect the address fields in the source and target structures.

Connect the fields with the same name in the Address and CustomerAddress
structures.
a) Select the Address and CustomerAddress substructures.
b) Choose the Assign Selected Fields and Substructures with Same Names
icon and confirm the subsequent warning by choosing Continue.
8. Create another message-mapping template.
Create an additional message-mapping template, this time with the
name AddressToAddress, between the data types Address and
CustomerAddress. An identical mapping is required between the source and
target fields Street, ZIPCode, and City.
a) Select the fields Address and CustomerAddress. Either call the context
menu for CustomerAddress and choose Create Template Based on
Mapping, or choose the Create Template Based on Mapping icon.
b) On the subsequent screen, enter the name as AddressToAddress and
confirm by choosing Create.
c) Save the mapping template.
9. Save the ContactToCustomer message mapping and display the mapping
templates used.
a) Save the message-mapping object.
Navigate back to the ContactToCustomer message mapping and save
the object.
b) List the message-mapping templates used in the message mapping.
Choose the Display Mapping Templates Used icon.

Hint: The system displays only one mapping template

(NameToCustName); the other mapping template was created
from the message mapping but not applied in it.

10. Test the mapping by using the mapping editor test function.
a) Choose the Test tab page and create a new XML instance by choosing
Generate Instance.
b) Expand the nodes in the XML instance and populate the fields with
test values.
c) Execute the mapping by choosing Execute Mapping.

186 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Message-Mapping Template

Lesson Summary
You should now be able to:
• Create mapping templates
• Use mapping templates in message mappings

2011 © 2011 SAP AG. All rights reserved. 187

Unit Summary BIT460

Unit Summary
You should now be able to:
• Define parameters for a mapping program
• Assign parameters to a mapping program at configuration time
• Use the term value mapping and therefore make use of advanced
message-mapping options
• Map multiple source and target messages
• Describe the procedure to use a multi-mapping in an interface determination
• Create mapping templates
• Use mapping templates in message mappings

188 © 2011 SAP AG. All rights reserved. 2011

 Unit 5
Other Mapping Types

Unit Overview
This course focuses on graphical message mapping. However, it is also relevant to
look at other mapping types that can be combined with message mapping.

Unit Objectives
After completing this unit, you will be able to:
• import and use XSLT mappings
• explain the main steps to create a Java mapping program
• Import and use a Java mapping in an Operation Mapping

Unit Contents
Lesson: Importing and Using XSLT Mapping ...............................190
Exercise 15: Import and Use XSLT Mappings ..........................195
Lesson: Creating a Java Mapping ............................................200
Exercise 16: Create and Use a Java Mapping .........................205

2011 © 2011 SAP AG. All rights reserved. 189

Unit 5: Other Mapping Types BIT460

Lesson: Importing and Using XSLT Mapping

Lesson Overview
This lesson looks at the way XSLT mappings work and how you can use them.

Lesson Objectives
After completing this lesson, you will be able to:
• import and use XSLT mappings

Business Example
You are responsible for the development of mappings in SAP PI and need to
know how to integrate XSLT mappings.

XSLT Mapping Within SAP PI

You can create XSLT mapping programs either as ABAP-XSL transformations
or directly in XSLT. XSLT is a transformation language used to describe
transformations of XML files. To transform an XML file, you require the source
document, the transformation statements (known as an XSL stylesheet), and an
XSLT engine to process the statements. You develop and test the stylesheet
externally in an appropriate XSLT editor before importing it into Enterprise
Services Repository.

• Develop the XSLT mapping program (stylesheet) locally.

• Create an archive (JAR or Zip) for the stylesheet.
• Create an Imported Archive in Enterprise Services Repository
• Import the XSLT archive into the Imported Archive.
• Reference the XSLT mapping program in the operation mapping.
If necessary, you can edit the XSLT file after it has been imported.
In the figure Example of an XSLT Mapping, the source field Class is mapped to
the target field Class. The value “business” is mapped to the value “2”.

190 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Importing and Using XSLT Mapping

Figure 55: Example of an XSLT Mapping

You have the option of using XPath statements in XSLT mappings. Like XSLT,
XPath is an XML specification. You can use XPath to address any elements in an
XML document. XSLT uses XPath to select substructures in XML documents.
The required transformations are executed for these substructures by using
templates defined in XSLT.
You can use the XSLT tags <xsl:include> and <xsl:import> to read
templates for substructures. In this way, you can break down a large XSLT
mapping program into smaller packages, and save them in one or more archives.
Furthermore, you can reuse XSLT templates for data types because they can be
called in other XSLT mappings.

• XSLT Mapping: transforms an XML document

• XPath: localizes substructures in an XML document
• <xsl:include> and <xsl:import> allow you to import additional
XSLT files
• <xsl:param> enables the runtime constants to be accessed
• External Java methods can be called in XSLT mappings

Using Java Methods in XSLT

In the figure below, the Java method merge is called from an XSLT stylesheet.
The call
xnlns:javamap=java:com.company.group.MappingClass defines
the namespace in which the class (and therefore also the method) is located.
The tag <xsl:value-of select=javamap:merge($first,

2011 © 2011 SAP AG. All rights reserved. 191

Unit 5: Other Mapping Types BIT460

$last)/> executes the call. Javamap selects the namespace defined above, and
merge($first, $last) calls the method merge. The result of
the method is shown in the resulting file.

Figure 56: Example of an XSLT Mapping Using the Method Merge

Runtime Constants
It is possible to use runtime constants that you use to read data that is not known
until runtime.

Important Runtime Constants

Runtime Constant Meaning
$SenderService Service at the sender that is to send the message
$ReceiverService Service at the receiver that is to receive the
message
$Direction Message direction (request, response, and fault)
$Interface Sender interface name
$InterfaceNamespace Sender interface namespace
$ReceiverName Receiver interface name
$ReceiverNamespace Receiver interface namespace

192 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Importing and Using XSLT Mapping

To access a constant in the XSLT program, it must first be declared as a parameter.

For example: <xsl:param name=“SenderService” />. Once declared, you can then
use the parameter just like any other XSLT parameter.

Accessing Runtime Constants

...
<xsl:param name="SenderService" />
...
<xsl:value-of select="$SenderService"/>

Trace Messages
To define warnings (that either cause processing to terminate or allow it to
continue), use the XSLT statement <xsl:message>.

Syntax and Example for the Statement

<xsl:message>
<xsl:message terminate=[yes|no]>
<!-- Output Message -->
</xsl:message>

// Example:
<xsl:message terminate="no">
This is a warning!
</xsl:message>

The XSLT statements in the following example test the current source value of the
test tag and set a corresponding target value. If neither of the two expected values
are found, the result is displayed as a warning, for example: <xsl:choose>
<xsl:when test="test()=0">Mr.</xsl:when>
<xsl:when test="test()=1">Mrs.</xsl:when>
<xsl:otherwise> Mr. or Mrs.
<xsl:message terminate="no">
Gender had neither 0 nor 1!
"Mr. or Mrs." was set as title.
</xsl:message>
</xsl:otherwise>
</xsl:choose<
This particular exception does not cause the mapping to terminate because the
parameter terminate was set to no.
Alternatively, you can define that a Java method is called in XSLT that writes
the messages to the trace log.

2011 © 2011 SAP AG. All rights reserved. 193

Unit 5: Other Mapping Types BIT460

SAP XML Toolkit deprecated

For PI 7.3 (which is based on JDK 6), the use of the SAP XML Toolkit is deprecated.

Note: Before PI 7.1, XSLT programs were executed using the SAP XML
Toolkit. This became obsolete when version 5 of the Java Development
Kit (JDK) was introduced with PI 7.1.

Compared to the SAP XML Toolkit, the usage of the JDK has the following
advantages:
• XSLT programs are executed more quickly
• Better error handling
• Supports a wider range of functions than the SAP XML Toolkit

Figure 57: XSLT Mapping - SAP XML Toolkit is deprecated

You will still be able to use the SAP XML Toolkit with PI 7.3. We recommend
to test existing XSLT programs and adjust them if necessary. So deselect the
option Use SAP XML Toolkit (which refers to the XSLT mapping program) in
the operation mapping.

194 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Importing and Using XSLT Mapping

Exercise 15: Import and Use XSLT

Mappings
Exercise Objectives
After completing this exercise, you will be able to:
• Import an XSLT mapping program that has been created externally into
Enterprise Services Repository
• Edit an imported XSLT mapping program
• Use an imported XSLT mapping program in an operation mapping

Business Example
You want to know the procedure for using an external XSLT mapping in an
operation mapping.

Task 1:
Import the XSLT mapping NameMerge.xsl for the mapping between the data types
MtCustomerName and MtPerson. Check that the mapping does not contain any
errors and use it in the operation mapping OM_CustomerInfoMap.
1. Import the NameMergeXSL.zip archive in Enterprise Services Repository
in software component version SC_BIT_MAP 1.0 in your namespace
http://educationsap.com/pi/mapping##.
2. Check that the XSLT mapping and adapt your group number.
3. Use the XSLT mapping in your operation mapping.
Make the necessary changes to your operation mapping
OM_CustomerInfoMap so that it uses your imported XSLT mapping
NameMerge.xsl.

Task 2: Testing the XSLT Mapping

Test the XSLT mapping by starting another call from the HTTP client.
1. Send a request from the HTTP client.
2. In the message monitor, check whether the XSLT mapping was used.

2011 © 2011 SAP AG. All rights reserved. 195

Unit 5: Other Mapping Types BIT460

Solution 15: Import and Use XSLT

Mappings
Task 1:
Import the XSLT mapping NameMerge.xsl for the mapping between the data types
MtCustomerName and MtPerson. Check that the mapping does not contain any
errors and use it in the operation mapping OM_CustomerInfoMap.
1. Import the NameMergeXSL.zip archive in Enterprise Services Repository
in software component version SC_BIT_MAP 1.0 in your namespace
http://educationsap.com/pi/mapping##.
a) Create new Imported Archive.
Expand the software component version node SC_BIT_MAP 1.0
followed by your namespace http://educationsap.com/pi/mapping##.
To create a new archive, call the context menu for Imported Archives
and choose New → Mapping Objects.
b) Specify archive parameters.
Enter NameMergeXSL as the name of the archive, leave the
namespace as http://educationsap.com/pi/mapping##, and choose
Create to create a new archive.
c) Import the XSL Stylesheet.
In the detail view for the archive, choose Tools → Import Archive to
import the archive NameMergeXSL.zip.
The Imported Archive now contains the XSL mapping NameMerge.xsl.
d) Save the archive.
2. Check that the XSLT mapping and adapt your group number.
a) Open the XSLT mapping.
Ensure you are in edit mode in the archive NameMergeXSL and then
choose Edit to open the XSLT mapping in change mode. Go to the
source text view.
b) Check the XSL stylesheet.
Check whether the XML document is a XSL stylesheet and which
namespaces are used:
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:ns="http://educationsap.com/pi/mapping##"

Continued on next page

196 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Importing and Using XSLT Mapping

xmlns:ns0="urn:educationsap.com:bit:mapping">
<xsl:output method="xml" version="1.0" indent="yes"/>

</xsl:stylesheet>

Ensure that you change ## to the number corresponding to your

namespace.
c) The declared template NameMerge is to be applied to the
source structure element MtCustomerName in the namespace
http://educationsap.com/pi/mapping##:

...
<xsl:template match="ns:MtCustomerName">
<xsl:call-template name="NameMerge"/>
</xsl:template>
</xsl:stylesheet>

d) The content of the NameMerge template is the merging of the source

fields Name and Surname, separated by a blank, and entered in the target
field MtName in the namespace urn:educationsap.com:bit:mapping :

...
<xsl:template name="NameMerge">
<ns0:MtName>
<xsl:value-of select="Name"/>
<xsl:text> </xsl:text>
<xsl:value-of select="Surname"/>
</ns0:MtName>
</xsl:template>
</xsl:stylesheet>

e) Activate the Imported Archive.

Close the editor window, save, and activate the archive NameMergeXSL.
3. Use the XSLT mapping in your operation mapping.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 197

Unit 5: Other Mapping Types BIT460

Make the necessary changes to your operation mapping

OM_CustomerInfoMap so that it uses your imported XSLT mapping
NameMerge.xsl.
a) Open the operation mapping.
In your namespace, navigate in the mapping objects to the operation
mappings and open your operation mapping OM_CustomerInfoMap
by double-clicking.
b) Switch to edit mode. First, under Mapping Program in the Request
area, use the input help to select the type XSL. Next, enter your new
XSLT mapping NameMerge under Name. Ensure that Use SAP XML
Toolkit is deselected.
c) Save and activate the changed operation mapping.

Task 2: Testing the XSLT Mapping

Test the XSLT mapping by starting another call from the HTTP client.
1. Send a request from the HTTP client.
a) Start the HTTP client.
Set the details for the sender service so that they match those for your
scenario configuration.
b) Choose Send to transfer the document to the pipeline.
2. In the message monitor, check whether the XSLT mapping was used.
a) Open the message monitor.
Call transaction SXI_MONITOR on the Integration Server. In the
Advanced tab, set the Client to 800. Check the processing of your
messages in the message monitor.
b) View the message trace.
Navigate to the detail view of your message and open the trace (under
SOAP Header → Trace) in the processing step Request Message
Mapping in either one of the windows.
c) At the very bottom of the trace area, you can find the message indicating
which operation mapping and mapping program were executed.

198 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Importing and Using XSLT Mapping

Lesson Summary
You should now be able to:
• import and use XSLT mappings

2011 © 2011 SAP AG. All rights reserved. 199

Unit 5: Other Mapping Types BIT460

Lesson: Creating a Java Mapping

Lesson Overview
This lesson looks at the way Java mappings have to be developed, and how you
can use them.

Lesson Objectives
After completing this lesson, you will be able to:
• explain the main steps to create a Java mapping program
• Import and use a Java mapping in an Operation Mapping

Business Example
You are responsible for the development of mappings in SAP PI and require an
overview of the options that are provided by Java mappings.

Steps to create a Java mapping program

You have to perform the following steps to use a Java mapping program in an
Operation Mapping:

• Develop the Java mapping program

in an Development Environment like SAP NetWeaver Developer Studio
• Create a JAR (or Zip) archive
with the compiled Java program as content
• Create an Imported Archive
in Enterprise Services Repository
• Import the JAR (or Zip) archive file
into the Imported Archive
Afterwards, you can reference the Java mapping program in an Operation
Mapping using the input help.

Note: You cannot edit Java programs in an Imported Archive.

200 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Java Mapping

Implementing a Java mapping program

To implement a Java mapping program, proceed as follows:

• Create a Java class extending the interface AbstractTransformation.

• Implement the method transform with the mapping.
The Java mapping API provides a framework only, without requiring a specific
type of implementation. For example, Java API for XML Processing (JAXP) is
available for processing XML documents.

Note: JAXP supports the Document Object Model (DOM) and the Simple
API for XML (SAX). The implementation is not in the focus of this lesson.

The required libraries are shipped with the installation of the AS Java in the
archive com.sap.xpi.ib.mapping.lib.jar (to be found in: usr/sap/<SID>/DVEB-
MGS<nr>/J2EE/cluster/bin/ext/com.sap.xi.mapping.tool.lib/lib).
The Java mapping API has been revised and this new API has to be used
for new Java mapping programs with PI 7.3. It is documented in SDN:
https://www.sdn.sap.com/irj/sdn/javadocs (SDN user required)
The following source code shows the main parts.

Java Mapping Template

import com.sap.aii.mapping.api.AbstractTransformation;
import com.sap.aii.mapping.api.StreamTransformationException;
import com.sap.aii.mapping.api.TransformationInput;
import com.sap.aii.mapping.api.TransformationOutput;
import com.sap.aii.mapping.api.InputHeader;
// ... additional imports

public class JavaMapping implements AbstractTransformation {

}
public void transform(TransformationInput in, TransformationOutput out)
throws StreamTransformationException {
try {
// do the mapping, for example using a DOM parser...
}}}

Hint: You can export the required XML schemas from Enterprise
Services Repository.

2011 © 2011 SAP AG. All rights reserved. 201

Unit 5: Other Mapping Types BIT460

Accessing Parameters and Header Fields

Accessing Parameters

public void transform(TransformationInput in, TransformationOutput out)

throws StreamTransformationException {
try {
...
// Use method to access parameters for parameterized mapping:
String inParam = in.getInputParameters().getString("PARAM_1");

You can access parameters specified in the Operation Mapping using the method
getInputParameters() of the in parameter, see coding above.
In this example, it is assumed that a parameter named PARAM_1 is specified in
the Operation Mapping.
You define the Java mapping parameters for a Java mapping program when you
create the binding in the operation mapping, and at the same time connect them to
operation mapping parameters. When you access the Java mapping parameters
in the Java mapping program, the mapping runtime checks whether you have
defined the parameters in the operation mapping. If they were not defined, an
exception is raised.

Accessing Header Fields

public void transform(TransformationInput in, TransformationOutput out)

throws StreamTransformationException {
try {
...
// Use get methods of InputHeader to access Header Fields:
InputHeader messageHeader = in.getInputHeader();
String messageId = messageHeader.getMessageId();

You can access header fields of the PI message using the

getInputHeader() method of the in parameter and subsequently
methods like getMessageId() for the messageId, see coding above.

202 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Java Mapping

Accessing adapter specific message

attributes

import com.sap.aii.mapping.api.DynamicConfiguration;
import com.sap.aii.mapping.api.DynamicConfigurationKey;
...

private static final DynamicConfigurationKey DYN_PARA =

DynamicConfigurationKey.create("http://sap.com/xi/XI/System/HTTP","UrlParamOne");

public void transform(TransformationInput in, TransformationOutput out)

throws StreamTransformationException {
try {
DynamicConfiguration conf = in.getDynamicConfiguration();
String myParaStr = "";
myParaStr = conf.get(DYN_PARA);
getTrace().addInfo(myParaStr);
...

You can access or set adapter specific message attributes with the
getDynamicConfiguration() method, see coding above.
DynamicConfiguration is a map containing adapter specific message attributes,
associating DynamicConfigurationKeys with string values.

Trace Messages
You can create entries in the mapping trace using the getTrace method of the
class AbstractTransformation:

Working with Trace in Java Mapping

public void transform(TransformationInput arg0, TransformationOutput arg1)

throws StreamTransformationException {
...
getTrace().addInfo("This is an information trace message.");

Note: Similar methods addWarning(String message); and

addDebugMessage(String message); can be used.

2011 © 2011 SAP AG. All rights reserved. 203

Unit 5: Other Mapping Types BIT460

Additional notes
• Not stateful: Java mappings must not be stateful, that is, nothing can be
written to the database. If a PI message is resent because of an error, this
can lead to database inconsistencies.
• Value Mapping: An API is available for executing value mappings. The
relevant classes are part of the package com.sap.aii.mapping.key.*.
• Lookup API: you can use an API for a Value Mapping Lookup. You
have to import a parameter of type Adapter into your Java mapping
(in.getInputParameters().getChannel("CommunicationChannelName");
).

204 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Java Mapping

Exercise 16: Create and Use a Java

Mapping
Exercise Objectives
After completing this exercise, you will be able to:
• Create a Java mapping program
• Import a Java mapping program that has been created externally into
Enterprise Services Repository
• Use an imported Java mapping program in an operation mapping

Business Example
You want to create a Java mapping program to use it in an operation mapping.

Task 1: Creating and Using a Java Mapping

Create and use a Java mapping program
1. Create a new Java project entitled CustomerInfo in the SAP NetWeaver
Developer Studio.
2. Create a new package com.educationsap.pi.mapping## in the
project CustomerInfo.
3. Import the example solution NameMergeJava.java to your project
CustomerInfo to package com.educationsap.pi.mapping##.
4. Adapt the example solution: change the package name suffix to your group
number.
5. Set the project reference to the library com.sap.xpi.ib.mapping.lib.jar
6. Compile the class NameMergeJava.java and generate a Java archive
NameMerge##.jar from the class file.
7. Import the NameMergeJava##.jar Java archive in Enterprise Services
Repository in software component version SC_BIT_MAP 1.0 in your
namespace http://educationsap.com/pi/mapping##.
8. Reference the java mapping program NameMerge.java in your operation
mapping OM_CustomerInfoMap.

Task 2: Testing a Java Mapping

Test the Java mapping by starting another call from the HTTP client.
1. Send a request from the HTTP client.
2. Check in the message monitor whether the Java mapping was used.

2011 © 2011 SAP AG. All rights reserved. 205

Unit 5: Other Mapping Types BIT460

Solution 16: Create and Use a Java

Mapping
Task 1: Creating and Using a Java Mapping
Create and use a Java mapping program
1. Create a new Java project entitled CustomerInfo in the SAP NetWeaver
Developer Studio.
a) Start the SAP NetWeaver Developer Studio.
To start the SAP NetWeaver Developer Studio, use the shortcut in the
archive.
b) Start the Project creation wizard.
Create a new project by choosing File → New → Project. Select the
type Java Project.
c) Specify the project attributes.
Choose Next to continue. Give the project the name CustomerInfo,
and leave all other settings as default.
d) Create the project; choose Finish.
2. Create a new package com.educationsap.pi.mapping## in the
project CustomerInfo.
a) Start the package creation.
In Package Explorer, select the CustomerInfo project and create a new
package by choosing File → New → Package.
b) Specify the package attributes.
Keep the Source Folder as CustomerInfo and enter
com.educationsap.pi.mapping## as the name of
the package.
c) Create the package; choose Finish.

Continued on next page

206 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Java Mapping

3. Import the example solution NameMergeJava.java to your project

CustomerInfo to package com.educationsap.pi.mapping##.
a) Start the import wizard.
Call the context menu for package com.educationsap.pi.mapping##
and choose Import.
b) Open the folder General, select the entry File System, and choose Next.
c) Set the import folder.
Choose Browse to navigate to the directory that contains the Java
mapping; choose OK to select that folder.
d) Import the java file.
Select the Java source code NameMergeJava.java from the list of files.
Keep the default value for Into Folder and start the import by choosing
Finish.
4. Adapt the example solution: change the package name suffix to your group
number.
a) Open the Java file NameMergeJava.java by double-clicking the name.
b) Correct your group number (##) in the package name (first line).

Hint: The com.educationsap.pi.mapping## package

corresponds to the http://educationsap.com/pi/mapping##
namespace.

c) The import statement references classes

com.sap.aii.mapping.api.* from the library
com.sap.xpi.ib.mapping.lib.jar.
d) In the method transform, the DOM parser is used to parse the XML
document.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 207

Unit 5: Other Mapping Types BIT460

5. Set the project reference to the library com.sap.xpi.ib.mapping.lib.jar

a) Open the project properties.
Use the Properties context menu for the project CustomerInfo.
b) Maintain the Java Build Path.
On the menu left-hand, choose Java Build Path. On the right-hand,
choose the Libraries tab page
c) Add external Jar.
Use the button Add External Jars to assign the file
com.sap.xpi.ib.mapping.lib.jar.
d) Close the Properties for CustomerInfo window by choosing OK.
6. Compile the class NameMergeJava.java and generate a Java archive
NameMerge##.jar from the class file.
a) SAP NetWeaver Developer Studio automatically compiles when you
save the Java class file.
b) Export the file into a jar file.
Call the context menu for package
com.educationsap.pi.mapping## and choose Export.
c) Select Java -> JAR file as the export destination and choose Next.
d) Set resources to export.
In the area Select the resources to export, select the package
CustomerInfo / src / com.educationsap.pi.mapping##, and in the
right-hand window, select NameMergeJava.java. Keep the selected
option Export generated class files and resources (you can only use the
compiled class in Java mapping).
For the field JAR file, choose Browse to select the directory and specify
the name NameMergeJava##.jar as the Export Destination, and keep
the selection option Compress the contents of the jar file.
e) Choose Finish to generate the Java archive NameMergeJava##.jar.

Continued on next page

208 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Java Mapping

7. Import the NameMergeJava##.jar Java archive in Enterprise Services

Repository in software component version SC_BIT_MAP 1.0 in your
namespace http://educationsap.com/pi/mapping##.
a) Create a new Imported Archive.
To create a new archive, call the context menu for Imported Archives
and choose New....
Enter NameMergeJava as the name of the archive, leave the
namespace as http://educationsap.com/pi/mapping##, and choose
Create to create a new archive.
b) Import the java archive.
In the detail view for the archive, choose Tools → Import Archive to
import the Java archive NameMergeJava##.jar.
The archive now contains the Java mapping NameMergeJava.class.
c) Save and activate the archive.
8. Reference the java mapping program NameMerge.java in your operation
mapping OM_CustomerInfoMap.
a) Open operation mapping.
In your namespace, navigate in the mapping objects to the operation
mappings and open your operation mapping OM_CustomerInfoMap
by double-clicking.
b) Delete the existing mapping program assignment.
Switch to edit mode. In the Request section, delete the existing line by
selecting the line and using the button Delete Selected Lines.
c) Reference the java mapping program.
Insert a new line. Use the drop-down menu to select the type Java
Class. Next, use the input help for the Name field to select your Java
mapping NameMerge.
d) Save and activate the changed operation mapping.

Continued on next page

2011 © 2011 SAP AG. All rights reserved. 209

Unit 5: Other Mapping Types BIT460

Task 2: Testing a Java Mapping

Test the Java mapping by starting another call from the HTTP client.
1. Send a request from the HTTP client.
a) Open the HTTP client.
This simulates an application that generates an XML document and
sends it to the SAP PI pipeline by using the HTTP adapter. Set the
details for the parameters so that they match those for your scenario
configuration (group number ##).
b) Choose Send to transfer the document to the pipeline.
2. Check in the message monitor whether the Java mapping was used.
a) Call transaction SXI_MONITOR on the Integration Server (client 800)
and check the processing of your message in the message monitor.
b) Navigate to the detail view of your message and open the trace (under
SOAP Header → Trace) in the processing step Request Message
Mapping in either one of the windows.
c) At the very bottom of the trace area, you can find the message indicating
which operation mapping and mapping program were executed.

210 © 2011 SAP AG. All rights reserved. 2011

BIT460 Lesson: Creating a Java Mapping

Lesson Summary
You should now be able to:
• explain the main steps to create a Java mapping program
• Import and use a Java mapping in an Operation Mapping

2011 © 2011 SAP AG. All rights reserved. 211

Unit Summary BIT460

Unit Summary
You should now be able to:
• import and use XSLT mappings
• explain the main steps to create a Java mapping program
• Import and use a Java mapping in an Operation Mapping

212 © 2011 SAP AG. All rights reserved. 2011

BIT460 Course Summary

Course Summary
You should now be able to:

• Create, test, and use message mappings

• Use advanced features of mapping types

2011 © 2011 SAP AG. All rights reserved. 213

Course Summary BIT460

214 © 2011 SAP AG. All rights reserved. 2011

 Feedback
SAP AG has made every effort in the preparation of this course to ensure the
accuracy and completeness of the materials. If you have any corrections or
suggestions for improvement, please record them in the appropriate place in the
course evaluation.

2011 © 2011 SAP AG. All rights reserved. 215