SAP Exchange Infrastructure
Mapping Functionality in XI
SAP AG 2002, Title of Presentation, Speaker Name 2
Overview Integration Builder
Mapping Introduction Overview Java Mapping XSLT Mapping ABAP Mapping
Message Mapping General Concepts Standard Functions Element Cardinality Context Handling User-Defined Functions Value Mapping Examples
SAP AG 2002, Title of Presentation, Speaker Name 3
Overview Integration Builder
Mapping Introduction
Message Mapping
SAP AG 2002, Title of Presentation, Speaker Name 4
Component Overview
Integration Builder (IB)
Integration Directory
(ID)
Integration Repository
(IR)
Integration Server
(IS)
System Landscape Directory (SLD)
Central Monitoring
SAP Systems
3rd Party Systems
3rd Party Middleware Component
Marketplace/ Business Partner
SAP AG 2002, Title of Presentation, Speaker Name 5
Integration Builder
Common client-server framework for all objects
Two instances of the framework Repository
Business Scenarios & Business Processes Interface Objects Mapping Objects Adapter Objects
Directory Party Service Receiver determination Interface determination Sender/Receiver Agreements
SAP AG 2002, Title of Presentation, Speaker Name 6
SAP Web AS 6.20
Design
Integration Repository
System Landscape Directory
Software Component
Software Component Version
J2EE/ABAP
Proxies
Message Interfaces Message Types
Integration Builder
Interface Editor Data Types
Business Processes
Mappings
Business Scenarios
Context Objects
Scenario Editor
Process Editor
Mapping Editor
Condition Editor
BPEL
XSLT Java
XPath
WSDL
XSD
SAP AG 2002, Title of Presentation, Speaker Name 7
Configuration
Integration Directory
Collaboration Profiles
Parties & Services Channels
Integration Builder
Business Processes
Routing Rules
Business Scenarios
Collaboration Agreements
Receiver Determination Rules
Interface Determination Rules (including Mapping Assignment)
Security
Configuration Editors
Configuration Wizards
SAP AG 2002, Title of Presentation, Speaker Name 8
Integration Server
Business Process Engine
Integration Processing
Integration Directory
Collaboration Agreements
Collaboration Profiles
Business Processes
Routing Rules
Business Scenarios
Receiver Determination Rules
Interface Determination Rules (including Mapping Assignment)
Integration Engine
Outbound Handling (also in adapters)
Business Process Execution
Inbound Handling (also in adapters)
Receiver Determination
Interface Determination
Channel Determination
Mapping
Parties & Services Channels
Security
SAP AG 2002, Title of Presentation, Speaker Name 9
Objects in the Integration Repository
Business Scenario Objects
Business Scenarios
Actions
Interface Objects Mapping Objects
Message Interfaces
Message Types
Fault Message Types
Data Types
Interface Mappings
Message Mappings
Imported Archives
Imported Objects (IDocs, RFCs)
References
Unified behaviour of all objects for change management, naming conventions, documentation,...
Business Processes
SAP AG 2002, Title of Presentation, Speaker Name 10
Integration Builder: Introduction
SAP AG 2002, Title of Presentation, Speaker Name 11
Object Handling in the Integration Repository
Before development can start Development manager or administrator has to
import a software component version from SLD Create namespaces in this software component version
Each repository object is uniquely identified by the triple software component version, namespace, object name
As a general rule: Software component : Namespace = 1 : n A namespace is transferred to a new version of a software component
after development is finished (Release-Transfer)
Object version management Changes are collected in (user-specific) change lists and can be activated once Each user may have different change lists
for each software component version he is working in After activation a new object version is released.
Old versions can be viewed by means of an object history.
SAP AG 2002, Title of Presentation, Speaker Name 12
Integration Builder XI 2.0 SP1: Software Logistics
Feature Purpose Objects from source -> destination
Role of target object
Copy (context menu)
Reuse
(global data types,
for example)
Within one Repository: SWCV1->SWCV2
SWCV1->SWCV1
Within one Directory
Copy with initial object
version
Release transfer (menu Tools)
(Only Repository)
Take over (all) objects to
next (or another) SWCV
of same repository at end
of development
Within one Repository: SWCV1->SWCV2
(single objects or
all objects of a namespace or
all objects of a SWCV)
Identical object with
same version as
source object
Export/ Import (context menu)
Transport,
shipment
Repository1 -> Repository2
(all objects of a namespace or
all objects of a SWCV)
Directory1 -> Directory2
Repository.:
Copy with same
version as source
object
Directory:
New initial object
version is created
SWCV: Software Component Version
SAP AG 2002, Title of Presentation, Speaker Name 13
Overview Integration Builder
Mapping Introduction Overview Java Mapping XSLT Mapping ABAP Mapping
Message Mapping
SAP AG 2002, Title of Presentation, Speaker Name 14
Peter Miller
Airline Kingdom AK087 2001-11-22 business
22.11.2001 087 Peter Miller 2 Happy Holiday
Overview - General Mapping Types
Mapping Transformation from one message structure to another Transformation rules defined by mapping program
Structure Mapping
Value Mapping
SAP AG 2002, Title of Presentation, Speaker Name 15
Integration Server
Business Process Engine
Mapping at Runtime
Integration Engine
Outbound Handling (also in adapters)
Business Process Execution
Inbound Handling (also in adapters)
Receiver Determination
Interface Determination
Channel Determination
Mapping
Messages in XI contain a sender interface
IS evaluates configuration data of the Integration Directory
During logical routing, the IS determines a Receiver Interface (1).
Such an interface pair can optionally reference an Interface Mapping
An interface mapping points to one or more mapping programs (for request, response and/or fault messages)
IS executes mapping programs (2)
Receiver determination and mapping step can also be performed within in the scope of BPM (1;2)
1
2
1;2
SAP AG 2002, Title of Presentation, Speaker Name 16
Interface Mapping(s)
Integration Repository
Request
Fault
Fault Message Type
Inbound Message Interface
Fault Message Type
Outbound Message Interface
Input Message Type
Response
Input Message Type
Output Message Type
Message Mapping XSLT Mapping Java Mapping
ABAP Mapping
Message Mapping XSLT Mapping Java Mapping
ABAP Mapping
Output Message Type
Message Mapping XSLT Mapping Java Mapping
ABAP Mapping
Overview - Relate Mapping Programs to Interfaces
SAP AG 2002, Title of Presentation, Speaker Name 17
Overview - Mapping Programs to Map Messages
Message Mapping Designed by using the graphical mapping editor of Integration
Builder Result: Generated Java Code.
Imported Archives Import externally defined mapping programs into repository Java mapping:
Implemented by using a specific interface XSLT mapping:
Runtime supports XSLT processor Java methods can be called from within a Style Sheet
ABAP Mapping
You can execute mapping programs in a sequence
SAP AG 2002, Title of Presentation, Speaker Name 18
Overview Integration Builder
Mapping Introduction Overview Java Mapping XSLT Mapping ABAP Mapping
Message Mapping
SAP AG 2002, Title of Presentation, Speaker Name 19
Java Mapping (I)
Mapping programs can be implemented in Java
1. Develop your Java code locally e.g. with your IDE
2. Create a .jar or a .zip
2.1 Using the jar command of the jdk
2.2 Using a built-in IDE functionality
3. Create a new Imported Archive and import the .jar to the Integration Repository
SAP AG 2002, Title of Presentation, Speaker Name 20
Java Mapping (II) - Development
Define a Java class that implements the Java interface com.sap.aii.mapping.api.StreamTransformation
The interface contains two methods: 1. public void execute(java.io.InputStream in,
java.io.OutputStream out)
to perform the mappings. 2. public void setParameter(java.util.Map param)
to access to runtime constants possible (for example: INTERFACE, SENDER_NAME)
The required libraries are contained in the aii_map_api.jar, which is part of your SAP J2EE Engine installation
DOM and SAX Parsers provided by the SAP XML Toolkit for Java can be used
API to execute value mappings
SAP AG 2002, Title of Presentation, Speaker Name 21
Java Mapping (III) - Template
SAP AG 2002, Title of Presentation, Speaker Name 22
Overview Integration Builder
Mapping Introduction Overview Java Mapping XSLT Mapping ABAP Mapping
Message Mapping
SAP AG 2002, Title of Presentation, Speaker Name 23
XSLT Mapping (I)
Proceeding equivalent as for Java mappings
1. Develop your XSLT files 2. Create a .jar or a .zip
2.1 Using the jar command of your jdk
2.2 Using a built-in IDE functionality
3. Create a new Imported Archive and import the .jar to the Integration Repository
4. Uploaded XSLT programs can modified within the XI Repository by means of a simple editor.
SAP AG 2002, Title of Presentation, Speaker Name 24
XSLT Mapping (II) - Features
XSL-Transformation: transforming XML structures XPath: Locating information in XML documents and : inclusion of other XSLT files to access runtime constants Invoking external Java methods from within an XSL
Transformation
SAP AG 2002, Title of Presentation, Speaker Name 25
XSLT Mapping (III) - Example
XSLT Mapping with Java Enhancement
Calls the method merge:
SAP AG 2002, Title of Presentation, Speaker Name 26
Overview Integration Builder
Mapping Introduction Overview Java Mapping XSLT Mapping ABAP Mapping
Message Mapping
SAP AG 2002, Title of Presentation, Speaker Name 27
ABAP Mapping (I)
Mapping programs can be implemented in ABAP
1. Add additional mapping types in your Exchange Profile: com.sap.aii.repository.mapping.additionaltypes =
R3_ABAP|Abap-class;R3_XSLT|XSL (ABAP Engine)
2. Develop your ABAP-OO class in the Object Navigator (se80)
3. Create a new Interface Mapping Select Mapping Type Abap-class
Enter the name of the ABAP-OO class
SAP AG 2002, Title of Presentation, Speaker Name 28
ABAP Mapping (II) - Development
Define a ABAP class that implements the interface IF_MAPPING of package SAI_MAPPING
The interface contains the method EXECUTE to perform the mappings.
The required libraries are contained in the aii_map_api.jar, which is part of your SAP J2EE Engine installation
DOM and SAX Parsers provided by the SAP XML Toolkit for Java can be used
API to execute value mappings
Parameter Direction Reference
SOURCE Importing XSTRING
PARAM IF_MAPPING_PARAM
TRACE IF_MAPPING_TRACE
RESULT Exporting XSTRING
SAP AG 2002, Title of Presentation, Speaker Name 29
Overview Integration Builder
Mapping Introduction
Message Mapping General Concepts Standard Functions Element Cardinality Context Handling Value Mapping User-Defined Functions Examples Mapping Patterns MultiMapping Mapping Template
SAP AG 2002, Title of Presentation, Speaker Name 30
Overview Integration Builder
Mapping Introduction
Message Mapping General Concepts Standard Functions Element Cardinality Context Handling Value Mapping User-Defined Functions Examples Mapping Patterns MultiMapping Mapping Template
SAP AG 2002, Title of Presentation, Speaker Name 31
General Concepts - Mapping Editor (I)
Data-Flow Editor
Structure Overview
Source Structure Target Structure
Target Field Mapping
SAP AG 2002, Title of Presentation, Speaker Name 32
General Concepts - Mapping Editor (II)
Import of source and target structure From Integration Repository
XSDs developped in the Integration Repository Imported External Definitions (WSDLs, XSDs, DTDs) Imported SAP meta data (RFCs, IDocs)
From local file system (XSD or XML) Not all XSD tags are supported (general rule: XSDs that can be
created by using the data type editor can be imported) and are not supported
Mapping editor displays a simplified XML representation of XSD files in structure overview
SAP AG 2002, Title of Presentation, Speaker Name 33
General Concepts - Mapping Editor (II)
Design message mapping using the data-flow editor Message mapping is composed of several target field
mappings You can edit one target field mapping in the data-flow editor All mandatory target fields (marked in red) must be mapped
SAP AG 2002, Title of Presentation, Speaker Name 34
Icon Status Display
Icon Meaning
Attribute
Element
Element with maxOccurs = unbounded
Icon Types
Icon Colors
Color Meaning White Attribute or element not assigned
Red Attribute or element must be assigned to complete the mapping
Yellow Attribute or element has already been assigned but the corresponding mapping in the data-flow editor is not complete
Green Mapping to target field complete
SAP AG 2002, Title of Presentation, Speaker Name 35
General Concepts - Elements
Attribute
Element is mandatory and might re-occur (minOccurs>0, maxOccurs>1)
Element is mandatory (minOccurs>0)
Parent node might repeat (maxOccurs>1)
Element might repeat (maxOccurs>1)
SAP AG 2002, Title of Presentation, Speaker Name 36
General Concepts - Elements
Elements
Nodes Do not contain any values
Attributes Attributes behave like elements
in mappings Attributes are marked with
@sign in the mapping editor.
SAP AG 2002, Title of Presentation, Speaker Name 37
General Concepts Assign Source/Target Message Types
There are 3 ways message types can be assigned to the Message Mapping.
1. By using an existing object already created in the Integration Repository (e.g. Message Type, External Definitions)
2. By using an RFC or IDoc meta data imported from SAP 3. By importing XML or XSD files from local file system
SAP AG 2002, Title of Presentation, Speaker Name 38
General Concepts Assignment of Fields (I)
drag&drop drag&drop drag&drop
Double click on a field =
navigate to mapping
Double click on a field =
insert field into data-flow editor
SAP AG 2002, Title of Presentation, Speaker Name 39
General Concepts - Assignment of Fields (II)
1.Mark root nodes of subtrees
2. Choose assignment function
Mappings are created automatically for homonymous child elements
SAP AG 2002, Title of Presentation, Speaker Name 40
General Concepts - DataFlow Editor
Delete Floating Objects Lay Out Mapping
Delete Current Mapping
Select Function Category
Define User
Function
Select Function
SAP AG 2002, Title of Presentation, Speaker Name 41
General Concepts Mapping Templates
1.Mark root nodes of subtrees 2. Choose Load
Mapping Template
Mapping Templates based on Date Types have to be created beforehand
Subnodes must reference this pair of Data Types
SAP AG 2002, Title of Presentation, Speaker Name 42
General Concepts - Text Preview
All target field mappings
Text Preview
Text Preview per target field
SAP AG 2002, Title of Presentation, Speaker Name 43
General Concepts - Dependencies
Dependencies
All mappings or mappings of two selected subnodes
are displayed
SAP AG 2002, Title of Presentation, Speaker Name 44
General Concepts Test Mappings (I)
A completed Message Mapping can be tested by using the Test tab.
Prerequisites 1. The defined message mapping must be complete. This means that each mandatory
target field must be assigned to one or more source fields. 2. There must not be any unassigned arguments when using functions.
Dropdown provides the creation and saving of test cases
Loads an XML instance from a local file.
Tabular Tree View
XML document view
Search node name in the Tabular Tree View
Execute Mapping
SAP AG 2002, Title of Presentation, Speaker Name 45
General Concepts Test Mappings (II)
Editing the XML instances to use in test cases:
Using the editor for the XML view, you can manually edit elements and attributes or their values here. Use CTRL C, CTRL X, and CTRL V respectively to copy, cut, and paste parts of an XML instance.
Using the context menu in the (Tabular) Tree View, you can copy sub-trees, delete nodes, and add elements and attributes. In the Value column in the tabular tree view you can also enter values for fields.
Enter test data
SAP AG 2002, Title of Presentation, Speaker Name 46
General Concepts Debug Mappings
Using the Display Queue to examine each step of the mapping:
Note: The context display and usage in the queues will be discussed in later slides.
SAP AG 2002, Title of Presentation, Speaker Name 47
Overview Integration Builder
Mapping Introduction
Message Mapping General Concepts Standard Functions Element Cardinality Context Handling Value Mapping User-Defined Functions Examples Mapping Patterns MultiMapping Mapping Template
SAP AG 2002, Title of Presentation, Speaker Name 48
Standard Functions: Introduction
All functions expect and return string values Generating functions produce values (for example: Constant) Some standard functions provide function properties (denoted by a
small asterisk) For example: concat lets you additionally specify a delimiter
Call the function properties window by double clicking the function
R = f(X1,X2) X1 X2
R
R = f(X1,X2,X3)
X1 X2 R X3
O = f(I) I O
O = Generated Value O
SAP AG 2002, Title of Presentation, Speaker Name 49
Simple Standard Functions: concat
Function category: Text
Source Message Mapping Target Message
Harry Potter
Harry Potter
concat properties Delimiter=
SAP AG 2002, Title of Presentation, Speaker Name 50
Simple Standard Functions: Substring
Function category: Text
counting starts at 0 !
Substring properties start from: 0 count: 10
Source Message Mapping Target Message
0123456789-181170
0123456789
SAP AG 2002, Title of Presentation, Speaker Name 51
Simple Standard Functions: DateTrans
Function category: Date
Source Message Mapping Target Message
181170
11/18/1970
DateTrans properties src Format: ddMMyy dst Format: MM/dd/yyyy
For potential date patterns, please see Java class java.text.DateFormat
SAP AG 2002, Title of Presentation, Speaker Name 52
Boolean Functions
Boolean functions Return true or false string Interpret 1 and true (not case-sensitive) as true-value
X
Z
Y
R then
if else
Result value if condition is true
Result value if condition is false
Condition R = Y if X is true or 1, else Z
R
X
Y
if
then
Condition
Result value if condition is true
R = Y if X is true or 1 or no tag is produced
ifWithoutElse
if
SAP AG 2002, Title of Presentation, Speaker Name 53
Calculations
Function category: Arithmetic
Calculations (add, multiply, etc.) are performed
with Java float precision Trailing zeros in result are truncated, e.g.: 4.2-0.2 = 4 To keep trailing zeros use FormatNum function
Source Message Mapping Target Message
90
90.00
FormatNum properties Number Format: ###,###,###.00
(For potential patterns, please see Java class java.text.DecimalFormat)
SAP AG 2002, Title of Presentation, Speaker Name 54
Overview Integration Builder
Mapping Introduction
Message Mapping General Concepts Standard Functions Element Cardinality Context Handling Value Mapping User-Defined Functions Examples Mapping Patterns MultiMapping Mapping Template
SAP AG 2002, Title of Presentation, Speaker Name 55
Element Cardinality Mandatory Mappings (minOccurs>0)
Mandatory Elements and Nodes (minOccurs>0) Mapping is mandatory. A source
element or a constant has to be assigned to the target element.
Otherwise error message: Message-mapping not completely defined
If not sufficient values are provided from the source structure during runtime, an exception is raised.
SAP AG 2002, Title of Presentation, Speaker Name 56
Element Cardinality Fixed Occurrences (minOccurs=maxOccurs)
Exception: Nodes with fixed occurrences (minOccurs=maxOccurs) Nodes are automatically marked in
green. Mapping is not mandatory.
Nodes are created automatically.
For elements with fixed occurrences the rules of mandatory elements are applied
SAP AG 2002, Title of Presentation, Speaker Name 57
Element Cardinality Repeating Elements (maxOccurs>1)
Mapping of Repeating Elements and Nodes (maxOccurs>1) Source: Target element is created as
often as mapped source element occurs in the source message.
Source: Creating function (e.g. Constant) If minOccurs>0, target
elements are created. If minOccurs=0, 1 target element is
created.
SAP AG 2002, Title of Presentation, Speaker Name 58
Element Cardinality Node Mapping
Mapping of non mandatory Nodes (minOccurs=0) If a non mandatory node
contains elements with minOccurs>0, these elements become mandatory after their parent node is assigned.
SAP AG 2002, Title of Presentation, Speaker Name 59
Element Cardinality Node Mapping (II)
Mapping of non mandatory Nodes (minOccurs=0) Assignment of elements is not
sufficient Node has to be created by
assigning a suitable source node/element
SAP AG 2002, Title of Presentation, Speaker Name 60
Element Cardinality Unique Target Mapping
Mapping from more than one Source element Only a single and unique
mapping relation per target element is allowed (n:1 relationship)
Multiple mapping relations can be defined by duplicating the target node or element (Duplicate Subtree)
To duplicate a node or an element, right-click on the object in the target structure pane and select Duplicate Subtree
SAP AG 2002, Title of Presentation, Speaker Name 61
Overview Integration Builder
Mapping Introduction
Message Mapping General Concepts Standard Functions Element Cardinality Context Handling Value Mapping User-Defined Functions Examples Mapping Patterns MultiMapping Mapping Template
SAP AG 2002, Title of Presentation, Speaker Name 62
Context Handling (I)
Context Change Message mapping works
internally by using queues If no further elements are
imported at a particular hierarchy level, a Context Change is inserted in the queue
Use node functions to handle changes in the message hierarchy.
SAP AG 2002, Title of Presentation, Speaker Name 63
Context Handling (II)
Why Queue Processing? No size limitations for messages Better runtime performance
Context changes have impact on:
User-Defined Functions Breaking and inserting of hierarchy levels
Manipulation of queues ant contexts
Explicit context selection on source elements and nodes Using node functions
removeContexts: deletes all context changes of a queue
SplitByValue: insert additional context changes in a queue
SAP AG 2002, Title of Presentation, Speaker Name 64
Context Handling - Show queue (I)
A tool to display queues:
1. Upload or create source xml-document in test mode
2. Right-click on box representing element or function
3. Select Show queue
SAP AG 2002, Title of Presentation, Speaker Name 65
Context Handling - Show queue (II) Example
Sender and Receiver Structure
Related Mapping
SAP AG 2002, Title of Presentation, Speaker Name 66
Context Handling - Show queue (III) Example
Show queue function display value queues leaving the related element/function.
Debugging functionality Applicable to any step in the mapping Step by step check of mappings
SAP AG 2002, Title of Presentation, Speaker Name 67
Context Handling - Show queue (IV)
Initial and terminal context change Not passed to the internal queue processing
Inner context change. Represented internally by constant ResultList.CC
Queue value
Suppressed value. Represented internally by constant ResultList.SUPPRESS. Suppressed when creating target element
The displayed queue contains the following values:
ResultList.SUPPRESS
ResultList.CC
toothpaste
ResultList.CC
ResultList.SUPPRESS
SAP AG 2002, Title of Presentation, Speaker Name 68
Context Handling - Node Functions removeContexts(I)
Source Message Mapping Target Message
SAP AG 2002, Title of Presentation, Speaker Name 69
Context Handling - Node Functions removeContexts (II)
Source Message Mapping Target Message
SAP AG 2002, Title of Presentation, Speaker Name 70
Source Message Mapping Target Message
one two three four
one two three four
Context Handling - Node Functions SplitByValue (I)
With SplitByValue
SplitByValue() is the counterpart to removeContexts()
inserts a context change in the source value queue. context change in the queue after each value, after each change to the value, or after an empty tag.
SAP AG 2002, Title of Presentation, Speaker Name 71
Source Message Mapping Target Message
one two three four
one two three four
Context Handling - Node Functions SplitByValue (II)
Without SplitByValue
SAP AG 2002, Title of Presentation, Speaker Name 72
Context Handling Explicit Context Selection (I)
Message Type XML representation
As of XI 2.0 SP3 the context of source nodes and elements can be selected explicitly
More precise handling as removeContexts function But: removeContexts function still necessary for context
manipulation within a mapping chain
Example:
SAP AG 2002, Title of Presentation, Speaker Name 73
Context Handling Explicit Context Selection (II)
Resulting Queue
Context
Explicit choice of contexts and resulting queues Context changes are relevant:
user-defined functions structure hierarchy
But: the removeContexts function is still necessary for context manipulation within a mapping chain :
SAP AG 2002, Title of Presentation, Speaker Name 74
Context Handling Explicit Context Selection (I)
Comparing two contexts with diverse numbers of entries: Last value of context with less elements is reiterated Applies also to Constants
Example: the content of the two contexts is concatenated; Value prodAttribute of /Fieldnames is reiterated to fill up result context.
SAP AG 2002, Title of Presentation, Speaker Name 75
Overview Integration Builder
Mapping Introduction
Message Mapping General Concepts Standard Functions Element Cardinality Node Functions Value Mapping User-Defined Functions Examples Mapping Patterns MultiMapping Mapping Template
SAP AG 2002, Title of Presentation, Speaker Name 76
Value Mapping (I) FixValues
The FixValues function provides a simple generic value mapping (or key mapping) in the Integration Repository
1. Use the standard function Conversions -> FixValues to link source and target element
2. Double click to define properties Each field mapping uses its
own table of key-value pairs. Filled tables can be copied to
other mappings. But copied table is independent of origin.
SAP AG 2002, Title of Presentation, Speaker Name 77
Value Mapping (II) Value mapping
The Value mapping function provides a more specific value transformation.
1. Use the standard function Conversions -> Value mapping to link source and target element
2. Double click to define properties 3. Define access keys for table entries:
Value Mapping Context stores information on the origin of the data. If data is maintained in the Integration Directory, use http://sap.com/xi/XI
Agency and Schema for sender and receiver messages. Any arbitrary string value can be used.
SAP AG 2002, Title of Presentation, Speaker Name 78
Value Mapping (III) - Value Mapping Group
Semantically identical information is collected in Value Mapping Groups Value Mapping Groups can be maintained:
in the Integration Directory by sending data to Message Interface ValueMappingReplication of SAP BASIS ->
SAP BASIS 6.40 -> http://sap.com/xi/XI/System
Following entries are required 1. Agency 2. Schema (Namespace and Object Type ) 3. Value (the groups representative for a given Agency Schema combination)
SAP AG 2002, Title of Presentation, Speaker Name 79
Value Mapping (VI) Define Value Mappings
Value Mappings are created automatically between representatives of the same group
All entries for a couple of Agency/Schema combinations are displayed using Tools-> Value Mapping in the Integration Directory
Each new entry will create automatically a new group.
SAP AG 2002, Title of Presentation, Speaker Name 80
Value Mapping (VI) Mass Configuration
Mass data can be maintained in Value Mappings tables by means of an XI Interface
Based on Message Interface ValueMappingReplication of http://sap.com/xi/XI/System in SC SAP BASIS 6.40
Configuration has to be created in Directory Provided data has to correspond to structure:
SAP AG 2002, Title of Presentation, Speaker Name 81
Overview Integration Builder
Mapping Introduction
Message Mapping General Concepts Standard Functions Element Cardinality Node Functions Value Mapping User-Defined Functions Examples Mapping Patterns MultiMapping Mapping Template
SAP AG 2002, Title of Presentation, Speaker Name 82
User-Defined Functions Overview
Functional enhancements if standard functions do not fulfill requirements
Is only visible in the message mapping in which you created it
Integration of Java programs from imported archives of the same software component version
Usage just like standard functions
SAP AG 2002, Title of Presentation, Speaker Name 83
User-Defined Functions Overview
UserDefined Function types: Simple functions, which can process individual field
input values for each function call. Simple functions, therefore, expect strings as input values and return a string. Advanced functions, which can process nonsingle
string field input values for each function call. You can pass either all field values of a context or the whole queue for the field in an array when calling the function. Each input field is passed as an array of String. Returned values are stored in a String array, ResultList.
SAP AG 2002, Title of Presentation, Speaker Name 84
User-Defined Functions Definition
Specify: Label:
Text that appears in the function chooser and on the data-flow object to identify the new function.
Argument Count: The number of input values that should be transferred to the function. Input values are of type java.lang.String
Description: Description of the functions use.
SAP AG 2002, Title of Presentation, Speaker Name 85
Define User
Function
User-Defined Functions Binding of external Classes (I)
SAP AG 2002, Title of Presentation, Speaker Name 86
User-Defined Functions Binding of external Classes (I)
Select Simple Function Single return value is of type java.lang.String
Import Java packages if required, e.g. sap.xi.mytools.*; sap.xi.myutils.*;
SAP AG 2002, Title of Presentation, Speaker Name 87
User-Defined Functions Binding of external Classes (I)
Example: following class should enhance a user-defined function
com.sap.aii.mappingtool.tf3.rt.Container
SAP AG 2002, Title of Presentation, Speaker Name 88
User-Defined Functions Binding of external Classes (II)
Procedure:
1. Compile your Java class and create a .jar
2. Create a new Imported Archive and upload your .jar.
3. The relevant class has to be declared in the Import statement
SAP AG 2002, Title of Presentation, Speaker Name 89
Advanced userdefined functions can access more than just individual values. A complete context or an entire queue can be accessed.
Message Mapping works by using queues. There is a queue for each hierarchy level.
Context Queue
User-Defined Functions Advanced Functions
SAP AG 2002, Title of Presentation, Speaker Name 90
Advanced userfunctions can import either just one context or the complete queue into input String arrays.
To import the complete queue, check the Cache Entire Queue checkbox in the function editor.
Working with Contexts or Queues
Information in Cache Implications
Context Do not have identifiable context change.
Queue Contains context change indicator. Much more memory intensive.
Context changes at the beginning and end of the context or queue are implicit and cannot identified.
User-Defined Functions Advanced Functions
SAP AG 2002, Title of Presentation, Speaker Name 91
User-Defined Functions Advanced Functions
Input parameters: String[] , ResultList, Container Flag Cache the whole queue
Selected: all values of the whole queue are passed to the function Not selected: values of one context is passed to the function
ResultList contains output of function Output builds up a new queue
SAP AG 2002, Title of Presentation, Speaker Name 92
User-defined functions String[]
Context changes are treated as fields They are represented by class variable java.lang.String ResultList.CC Queue output determines input values of user-defined functions First and last context change of each queue are suppressed
Caching the whole queue Not caching the whole queue
String[] a =
{"A.1.1","A.1.2",
ResultList.CC,"A.2.1",
ResultList.CC,"A.3.1",
ResultList.CC,"B.1.1",
ResultList.CC,"B.2.1",
"B.2.2"};
String[] a =
{"A.1.1", "A.1.2"};
{"A.2.1"};
{"A.3.1"};
{"B.1.1"};
{"B.2.1","B.2.2"};
String[] a =
{"A.1.1","A.1.2",
"A.2.2","A.3.1",
ResultList.CC,"B.1.1",
"B.2.1","B.2.2"};
String[] a =
{"A.1.1", "A.1.2",
"A.2.1","A.3.1"};
{"B.1.1","B.2.1",
"B.2.2"};
SAP AG 2002, Title of Presentation, Speaker Name 93
User-defined functions Container
Container supports the methods void setParamter(String, Object)
Object getParameter(String)
Stalled parameters can be accessed in this specific function GlobalContainer getGlobalContainer()
MappingTrace getTrace()
Map getTransformationParameters()
Map can be used to get runtime constants, e.g. Object map.get(StreamTransformationConstants.SENDER_SYSTEM)
GlobalContainer supports the methods void setParamter(String, Object)
Object getParameter(String)
Stalled parameters can be accessed in different functions of one message mapping
MappingTrace supports the methods void addWarning(String) trace level: 1, 2, 3 void addInfo(String) trace level: 2, 3 void addDebugMessage(String) trace level: 3 Writes String to message monitoring
SAP AG 2002, Title of Presentation, Speaker Name 94
User-defined functions ResultList
ResultList supports the methods and constants
void addValue(String)
void addContextChange()
void addSuppress()
void clear()
ResultList.CC (context change)
ResultList.SUPPRESS (suppressed value)
Outbound queue has to be build up manually, i.e. in case you cache the whole queue values, context changes and suppressed values have to be added manually.
SAP AG 2002, Title of Presentation, Speaker Name 95
User-defined functions function types
Simple Functions Advanced Functions
Input Parameters
String, , Container String[], , ResultList,
Container
Returning Values
return String; result.addValue(String);
Processing Function is called once per field mapping
Function is called once per context or queue. Values of context /queue are stored in input string arrays
SAP AG 2002, Title of Presentation, Speaker Name 96
Overview Integration Builder
Mapping Introduction
Message Mapping General Concepts Standard Functions Element Cardinality Node Functions Value Mapping User-Defined Functions Examples Mapping Patterns MultiMapping Mapping Template
SAP AG 2002, Title of Presentation, Speaker Name 97
Examples Get value by key (I)
Problem: A specific value should be filtered by a key or qualifier Example: only English should be mapped to resulting field
SAP AG 2002, Title of Presentation, Speaker Name 98
Examples Get value by key (II)
1. Create mapping
2. Set Contexts of and
Solution:
SAP AG 2002, Title of Presentation, Speaker Name 99
Examples Get value by key (III)
3. Display Queues to investigate
4. Explanation Since the element may only occur once in the resulting structure, the output has to be put in a single context. The two suppressed values are removed automatically when the resulting document is created
In an alternative solution two contexts of and keep their initial contexts and a removeContexts is inserted after the ifWithoutElse function.
Discussion:
SAP AG 2002, Title of Presentation, Speaker Name 100
Examples Copy head to line (I)
Problem: A hierarchical structure has to be mapped to a flat structure One should be created per Header information (represented ) occurring only once per
should be multiplied and copied to .
SAP AG 2002, Title of Presentation, Speaker Name 101
Examples Copy head to line (II)
1. Create User-Defined Function
2. Create mappings
Solution:
SAP AG 2002, Title of Presentation, Speaker Name 102
Examples Copy head to line (III)
3. Display Queues
4. Explanation The User-Defined Function copyPerValue copies the value of per each occurrence of to the relevant context. The SplitByValue function then distributes the copied values to the contexts of the flat structure.
Since only contains empty fields, you can use in this case also function concat instead of copyPerValue. See Context Handling Explicit Context Selection (I) for details.
Discussion:
SAP AG 2002, Title of Presentation, Speaker Name 103
Overview Integration Builder
Mapping Introduction
Message Mapping General Concepts Standard Functions Element Cardinality Node Functions Value Mapping User-Defined Functions Examples Mapping Patterns MultiMapping Mapping Template
SAP AG 2002, Title of Presentation, Speaker Name 104
Mapping Patterns
Mapping patterns are some of the common mapping requirements we found in the past which XSLT was used, because we did not think that Message Mapping provided the functionality
Summarization SequenceNumber Generation Duplicating Subtrees Table / Value Lookups TreeReversal
SAP AG 2002, Title of Presentation, Speaker Name 105
Summarization is when we try to consolidate detailed information into total/subtotals and counts.
The count and sum functions will act on the content of a context. Therefore, the context of the group to be summarized must be selected appropriately.
Example:
Mapping Patterns Summarization
Target: Total and count the order by each customer and a summary of all orders
Source: Order details containing customer, order numbers and order amount
SAP AG 2002, Title of Presentation, Speaker Name 106
Mapping Patterns Summarization
SAP AG 2002, Title of Presentation, Speaker Name 107
Mapping Patterns Summarization
Mapping Result:
SAP AG 2002, Title of Presentation, Speaker Name 108
Mapping Patterns SequenceNumber Generation
There are situations when sequence numbers had to be generated based on the number of occurrences of the source data. This is frequently used during mapping to SAP IDocs or BAPIs when item number, which is no available from the source, had to be entered.
Example:
Source: Order information.
Target: Two complex elements had to be populated from the source. Each one contains a sequence number which matches the position of the data in the source.
Sequence number to be generated.
SAP AG 2002, Title of Presentation, Speaker Name 109
Mapping Patterns SequenceNumber Generation
There are two ways the sequence number can be generated.
1. Use Advanced UserDefined function to generate the sequence number all at once.
2. Use Simple UserDefined function to generate the sequence number for each occurrence separately, keeping track of the sequence number value previously generated.
SAP AG 2002, Title of Presentation, Speaker Name 110
Mapping Patterns SequenceNumber Generation
1. Use Advanced UserDefined function to generate the sequence number all at once.
The java function creates the sequence number all at once based on the number of elements in the source. The sequence numbers are written to the ResultList object.
SAP AG 2002, Title of Presentation, Speaker Name 111
Mapping Patterns SequenceNumber Generation
1. Use Advanced UserDefined function to generate the sequence number all at once.
SAP AG 2002, Title of Presentation, Speaker Name 112
Mapping Patterns SequenceNumber Generation
1. Use Advanced UserDefined function to generate the sequence number all at once.
Test Results:
SAP AG 2002, Title of Presentation, Speaker Name 113
Mapping Patterns SequenceNumber Generation
2. Use Simple UserDefined function to generate the sequence number for each occurrence separately, keeping track of the sequence number value previously generated.
The sequence number is stored in the container object. Each time it is retrieved, incremented and saved. Note: There is no input required.
SAP AG 2002, Title of Presentation, Speaker Name 114
Mapping Patterns SequenceNumber Generation
2. Use Simple UserDefined function to generate the sequence number for each occurrence separately, keeping track of the sequence number value previously generated.
We cannot display the queue to examine the result of the mapping.
SAP AG 2002, Title of Presentation, Speaker Name 115
Mapping Patterns SequenceNumber Generation
2. Use Simple UserDefined function to generate the sequence number for each occurrence separately, keeping track of the sequence number value previously generated.
SAP AG 2002, Title of Presentation, Speaker Name 116
Mapping Patterns Duplicating Subtrees
Even if elements are shown to occur more than once in the XML instance according to XML Schema Definition, they are only displayed once in the structure overview.
To assign source field(s) to multiple positions of an element in the target structure, the element or the entire subree can be duplicated (copied) using the context menu in the target structure.
Example:
Source: Accounting information with adjustment type and amount.
Target: Two CurrencyAmts are to be created. One is to credit one account. The other is to debit another account. The amount will either be positive or negative depending on the ADJTYPE.
SAP AG 2002, Title of Presentation, Speaker Name 117
Mapping Patterns Duplicating Subtrees
The subtree CurrencyAmt must be duplicated first. This will create 2 CurrencyAmts. One for credit, and one for debit.
SAP AG 2002, Title of Presentation, Speaker Name 118
Mapping Patterns Duplicating Subtrees
SAP AG 2002, Title of Presentation, Speaker Name 119
Mapping Patterns Duplicating Subtrees
Mapping Results:
SAP AG 2002, Title of Presentation, Speaker Name 120
Mapping Patterns Table/Value Lookup
During mapping, a lookup is necessary in a different subtree structure of the XML document. This lookup process is easily accomplished using XSLT, since we can navigate the XML document using absolute or relative path specification. In Message Mapping, there is no facility to navigate the XML document.
In Message Mapping, we have to use the context of the different elements required for the lookup. A Java function will be needed to perform the comparisons. And, the matched values will have to be written to ResultList.
Example:
Source: Contains credit card information, with 2 subtrees. One is account information (including account number, cost center, subaccount, card type, etc.) The 2nd subtree contains detailed billing information (including account number, date, billing amount, etc.)
Target: Contains only detailed billing information, but with each billing record, the cost center, subaccount and card type from the account info record must also be included. The account number in the detail is used to do the lookup of the account information records.
SAP AG 2002, Title of Presentation, Speaker Name 121
Mapping Patterns Table/Value Lookup
Source: Target:
=
SAP AG 2002, Title of Presentation, Speaker Name 122
Mapping Patterns Table/Value Lookup
Java Function:
The lookupd value must be written to the ResultList.
SAP AG 2002, Title of Presentation, Speaker Name 123
Mapping Patterns Table/Value Lookup
Mappings for all 3 elements are identical, except for the element names.
Contexts must be set a root level.
SAP AG 2002, Title of Presentation, Speaker Name 124
Mapping Patterns Table/Value Lookup
Mapping Results:
SAP AG 2002, Title of Presentation, Speaker Name 125
Mapping Patterns TreeReversal
Below is a mapping scenario which reverses the parent and child nodes. A reverse summarizations is also performed.
Source document: Target document:
The products are to be sorted and totaled by prices with the orderids listed.
SAP AG 2002, Title of Presentation, Speaker Name 126
Mapping Patterns TreeReversal
The source document is organized by orderid, product and price. The same product can occur in more than 1 orders.
The target document is summarized by product with a total price and listed within each product all the orderids. The same orderids can occur in more than 1 products.
The mapping needs to reverse the organization of the source document.
Based on that, the following needs to be done using the contexts/queues used by Message Mapping:
1. Get a list of all the products. Since the same product can be in multiple orders, we must eliminate the duplicates, and, then, sort them.
2. Sum the prices by product and assign those totals to the products in their sorted order.
3. Examine all the orderids and determine which orderids contain each of the products in the sorted list. Then, assign those orderids to the products.
SAP AG 2002, Title of Presentation, Speaker Name 127
Mapping Patterns TreeReversal
Three Java functions were written to:
1. Extract the products, eliminate duplicate names, and sort them in alphabetical order.
SAP AG 2002, Title of Presentation, Speaker Name 128
Mapping Patterns TreeReversal
2. Total the prices and assign the total to the appropriate products.
SAP AG 2002, Title of Presentation, Speaker Name 129
Mapping Patterns TreeReversal
3. Retrieve all the orderids and assign them to the appropriate products.
Note:
Cache Entire Queue is checked.
When the product is being retrieved, the Context Change is skipped.
The Context Change is added to the ResultList.
SAP AG 2002, Title of Presentation, Speaker Name 130
Mapping Patterns TreeReversal
Mapping for ITEM: To create the number of elements.
SAP AG 2002, Title of Presentation, Speaker Name 131
Mapping Patterns TreeReversal
Mapping for the attribute NAME, which is the product name.
SAP AG 2002, Title of Presentation, Speaker Name 132
Mapping Patterns TreeReversal
Display Queue for determining NAME:
SAP AG 2002, Title of Presentation, Speaker Name 133
Mapping Patterns TreeReversal
Mapping to create the number of element for ORDERS_WHERE_ITEM_IS_FOUND.
SAP AG 2002, Title of Presentation, Speaker Name 134
Mapping Patterns TreeReversal
Mapping for the attribute TotalSalesFOrThisItem, which totals the prices by product name.
SAP AG 2002, Title of Presentation, Speaker Name 135
Mapping Patterns TreeReversal
Display Queue for determining TotalSalesFOrThisItem:
SAP AG 2002, Title of Presentation, Speaker Name 136
Mapping Patterns TreeReversal
Mapping for the element ORDERID, which will be listed by product name.
SAP AG 2002, Title of Presentation, Speaker Name 137
Mapping Patterns TreeReversal
Display Queue for determining ORDERID:
SAP AG 2002, Title of Presentation, Speaker Name 138
Mapping Patterns TreeReversal
Partial listing of the mapping results:
SAP AG 2002, Title of Presentation, Speaker Name 139
Overview Integration Builder
Mapping Introduction
Message Mapping General Concepts Standard Functions Element Cardinality Node Functions Value Mapping User-Defined Functions Examples Mapping Patterns MultiMapping Mapping Template
SAP AG 2002, Title of Presentation, Speaker Name 140
MultiMappings
MultiMapping can only be used in ccBPM: Used to map abstract interfaces Development is the same as Message Mappings n:1 Transformation Bundles multiple messages into one message, for example, individual purchase
order items into one purchase order. 1:n Transformation Splits a message into multiple messages, for example, a purchase order into
the individual purchase order items. n:m Transformation Converts a message into another message, for example, a message that is
defined by interface A is converted to message that is defined by interface B. MultiMappings reference multiple message structures: All source message structures are combined into 1 source structure. All target message structures are combined into 1 target structure. Therefore, there is only one source structure mapped to one target.
SAP AG 2002, Title of Presentation, Speaker Name 141
Mapping Patterns MultiMappings
The Message Types are entered using the Messages tab in the mapping editor. The root element is always . The Mapping Editor inserts an element for each source or target message, where N
is the position of the message.
Example: Message Type (Source) Message Type (Target)
OrderHeader(1) Order(1)
OrderItem(0unbounded) OrderInfo(1)
SAP AG 2002, Title of Presentation, Speaker Name 142
Mapping Patterns MultiMappings
Insert more messages
Change Occurrences
No msg type name
Mapping rules are the same as for previously discussed Message Mappings.
SAP AG 2002, Title of Presentation, Speaker Name 143
Overview Integration Builder
Mapping Introduction
Message Mapping General Concepts Standard Functions Element Cardinality Node Functions Value Mapping User-Defined Functions Examples Mapping Patterns MultiMapping Mapping Template
SAP AG 2002, Title of Presentation, Speaker Name 144
Mapping Templates
Message Mappings can be saved as Mapping Templates.
Mapping Templates can be reused (or loaded) in other Message Mappings or Mapping Templates.
Features:
Mapping Templates can be defined for structure mappings of the following structures: Data Types Complex types in IDocs and RFCs Complex types in External Definitions The referenced types used in mapping templates can be located in any
software component versions.
SAP AG 2002, Title of Presentation, Speaker Name 145
Mapping Templates
The Mapping Editor is used to create and load the structures used by the Mapping Templates.
Defining Mapping Templates The Mapping Template can be saved by:
1. Selecting the Source and Target source in the Mapping Editor 2. Choose Save Mapping Template from either the target structure context menu or
from the object toolbar 3. Enter a unique name for the new Mapping Template.
SAP AG 2002, Title of Presentation, Speaker Name 146
Mapping Templates
Using Mapping Templates:
Mapping Templates can be used in Message Mappings from any software component version:
1. In the Mapping Editor, select a type element in the source and target structure. 2. Choose Load Mapping Templates from either the target structure context menu or from
the object toolbar. 3. If mapping templates are available for the types in the source and target fields, a select
dialog window will be displayed.
The Types must match what were defined in the existing Mapping Templates.
SAP AG 2002, Title of Presentation, Speaker Name 147
Further Information
Public Web: http://help.sap.com http://sdn.sap.com http://service.sap.com SAP Customer Services Network: http://www.sap.com/services/
Related XI 3.0 Workshop / Training Opportunities NetWeaver04 Overview
XI 3.0 Implementation Workshop
Introduction to XML and Technical Standards
Advanced Integration Builder
Advanced BPM
Adapter Framework
B2B and Industry Standards
Proxy Development and Deployment
SAP AG 2002, Title of Presentation, Speaker Name 148
Q&A
Questions?