mapping functional it yin xi

8/6/2019 Mapping Functional It Yin Xi

http://slidepdf.com/reader/full/mapping-functional-it-yin-xi 1/150



© 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





Mapping – Introduction

Message Mapping




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




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 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

XSLTJava

XPath

WSDL

XSD




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




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




Objects & Object References in the Integration Repository

WSDL

Message-Interface

Data Type Context Object

Interface-Mapping

Message-Mapping

Mapping-Template

RFC IDoc

External Definition

Message

Request-Message

Response-Message

Fault-Message

Business Scenario

Business-Prozess Action

Object ref.

Sub-Object Ref.

Interface-ObjectsMapping-Objects

Business Scenarios & -Processes

Imported Objects


Adapter Objects

( Fault-) Message-Type

Data Type Enhancement

Adapter Metadata

Comm.-Channel Template




Integration Builder: Introduction




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 triplesoftware 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 componentafter development is finished (Release-Transfer)

Object version management

Changes are collected in (user-specific) change lists and can be activatedonce

Each user may have different change lists

After activation a new object version is released.Old versions can be viewed by means of an object history .




Integration Builder: Software Logistics

Repository.:

Copy with same

version as source

object

Directory:

New initial object

version is created

Repository1 -> Repository2

(all objects of a namespace or

all objects of a SWCV)

Directory1 -> Directory2

Transport,

shipment Export/

Import(context menu)

Identical object with

same version as

source object

Within one Repository:

SWCV1->SWCV2

(single objects or

all objects of a namespace or

all objects of a SWCV)

Take over (all) objects to

next (or another) SWCV

of same repository at end

of development

Release

transfer (menu “Tools”)

(Only Repository)

Copy with initial object

version

Within one Repository:

SWCV1->SWCV2

SWCV1->SWCV1

Within one Directory

Reuse

(global data types,

for example)

Copy(context menu)

‘Role’ of targetobject

Objects fromsource -> destination

PurposeFeature

SWCV: Software Component Version






Java Mapping


Message Mapping




<hh:book-flight xmlns:hh="...">

<hh:customer >

<hh:first-name>Peter </hh:first-name>

<hh:surname>Miller </hh:surname></hh:customer >

<hh:booking-data>

<hh:airline>Airline Kingdom</hh:airline>

<hh:connection>AK087</hh:connection>

<hh:date>2001-11-22</hh:date>

<hh:class>business</hh:class>

</hh:booking-data>

</hh:book-flight>

<ak:BookFlight xmlns:ak="...">

<ak:Date>22.11.2001</ak:Date><ak:Flight>087</ak:Flight>

<ak:Passenger >Peter Miller </ak:Passenger >

<ak:Class>2</ak:Class>

<ak:Agency>Happy Holiday</ak:Agency>

</ak:BookFlight>

Overview - General Mapping Types

Mapping Transformation from one message structure to another

Transformation rules defined by mapping program

Structure Mapping

Value

Mapping




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 mappingpoints to one or more

mapping programs

(for request, response

and/or fault messages)

• IS executes mappingprograms (2)

• Receiver determination

and mapping step can also

be performed within in the

scope of BPM (1;2)

1

2

1;2




Interface Mapping(s)Integration Repository

R e

q u e s t

F a ul t

Fault

Message Type

Inbound

Message Interface

Fault

Message Type

Outbound

Message Interface

InputMessage Type

R

e s p on s e

Input

Message Type

OutputMessage Type

Message Mapping

XSLT Mapping

Java Mapping

ABAP Mapping

Message Mapping

XSLT Mapping

Java Mapping

ABAP Mapping

Output

Message Type

Message MappingXSLT Mapping

Java Mapping

ABAP Mapping

Overview - Relate Mapping Programs to Interfaces




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






Java Mapping


Message Mapping




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 .zip2.1 Using the jar command of

the jdk

2.2 Using a built-in IDE

functionality3. Create a new Imported Archive

and import the .jar to the





Java Mapping (II) - Development

Define a Java class that implements the Java interfacecom.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 theaii_map_api.jar, which is part of your SAP J2EEEngine installation

DOM and SAX Parsers provided by the SAP XML Toolkit

for Java can be used API to execute value mappings




Java Mapping (III) - Template






Java Mapping


Message Mapping




XSLT Mapping (I)

Proceeding equivalent as for Java

mappings

1. Develop your XSLT files

2. Create a .jar or a .zip2.1 Using the jar command of

your jdk

2.2 Using a built-in IDE

functionality3. Create a new Imported Archive

and import the .jar to the


4. Uploaded XSLT programs canmodified within the XI

Repository by means of a

simple editor.




XSLT Mapping (II) - Features

XSL-Transformation: transforming XML structures

XPath: Locating information in XML documents

<xsl:include> and <xsl:import>: inclusion of other XSLT files

<xsl:param> to access runtime constants

Invoking external Java methods from within an XSL

Transformation




XSLT Mapping (III) - Example

XSLT Mapping with Java Enhancement

Calls the method merge:






Java Mapping


Message Mapping




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




ABAP Mapping (II) - Development

Define a ABAP class that implements the interfaceIF_MAPPING of package SAI_MAPPING

The interface contains the method EXECUTE to perform the

mappings.

You might use the iXML library in an ABAP Objects

environment to parse your document

XSTRINGExportingRESULT

IF_MAPPING_TRACETRACE

IF_MAPPING_PARAMPARAM

XSTRINGImportingSOURCE

ReferenceDirectionParameter




ABAP Mapping (III) - Template

method if_mapping~execute.

* initialize iXML

type-pools: ixml.

class cl_ixml definition load.

* create stream factory

data: streamfactory type ref to if_ixml_stream_factory.streamfactory = ixmlfactory->create_stream_factory( ).

* create input stream

data: istream type ref to if_ixml_istream.

istream = streamfactory->create_istream_xstring( source ).

* …* get XI parameter

data: l_sender_service type string.

l_sender_service = param->get( if_mapping_param=>sender_service ).

* …

* create output stream

data: oStream type ref to if_ixml_ostream.

oStream = streamfactory->create_ostream_xstring( result ).* …

endmethod.






Message Mapping

General Concepts Standard Functions

Element Cardinality

Context Handling

Value Mapping User-Defined Functions

Examples

Mapping “Patterns”

Multi–Mapping

Mapping Template






Message Mapping


Element Cardinality

Context Handling


Examples


Multi–Mapping

Mapping Template

G l C t M i Edit (I)




General Concepts - Mapping Editor (I)

Data-Flow Editor

Structure Overview

Source Structure Target Structure

Target Field Mapping

General Concepts Mapping Editor (II)




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)

<xsd:include> and <xsd:import> are not supported

Mapping editor displays a simplified XML representation

of XSD files in structure overview

General Concepts Mapping Editor (III)




General Concepts - Mapping Editor (III)

There are 3 ways structures 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

General Concepts Mapping Editor (IV)




General Concepts - Mapping Editor (IV)

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

Icon Status Display




Icon Status Display

Element with maxOccurs = unbounded

MeaningIcon

Node

Element

Attribute

Icon Types

Icon Colors

Mapping to target field completeGreen

Attribute or element has already been assigned but the

corresponding mapping in the data-flow editor is not

complete

Yellow

Attribute or element must be assigned to complete the

mapping

Red

Attribute or element not assignedWhite

MeaningColor

General Concepts - Elements




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)

General Concepts – Assignment of Fields




General Concepts Assignment of Fields

drag&dropdrag&dropdrag&drop

Double click on a

field=navigate tomapping

Double click on afield

=insert field intodata-flow editor

General Concepts - Data–Flow Editor




General Concepts Data Flow Editor

Delete

FloatingObjects

Lay OutMapping

DeleteCurrentMapping

SelectFunctionCategory

DefineUser Function

Select

Function

General Concepts – Mass Assignment




General Concepts Mass Assignment

1.Mark root nodesof subtrees

2. Chooseassignment function

• Mappings are created automatically for homonymous child elements

General Concepts – Mapping Templates




Ge e a Co cepts app g e p ates

1.Mark root nodesof subtrees

2. Right-click onnode. Choose “ShowSuitable Templates”

• Mapping Templates based on Date Types have to be created beforehand

• Subnodes must reference this pair of Data Types

General Concepts - Text Preview




p

All target field mappings

Text Preview

Text Preview per target field

General Concepts - Dependencies




p p

Dependencies

All mappings or mappings of two selectedsubnodes are displayed

General Concepts – Test Mappings (I)




p pp g ( )

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

Prerequisites

The defined message mapping must be complete. This means that each mandatory

target field must be assigned to one or more source fields.

There must not be any unassigned arguments when using functions.

Create test

cases

Tree View

XML document

view

Execute

Mapping

Create

empty

template

Loads an XML

instance from a

local file.

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 valueshere.

Using the Tree View , you can copy

sub-trees, delete nodes, and add

elements and attributes. In the

Value column you can also enter

values for fields.

Enter test

data

General Concepts – Debug Mappings




Using the “Display Queue” to examine each step of the mapping:

Note:

The “context”

display andusage in the

queues will be

discussed in

later slides.







Message Mapping


Element Cardinality

Context Handling


Examples


Multi–Mapping Mapping Template

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(X 1 ,X 2 )X1

X2

R

R = f(X 1 ,X 2 ,X 3 )

X1

X2 R

X3

O = f(I)I O

O =Generated Value O

Simple Standard Functions: concat




Function category: Text

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

<Contact><Fullname>

Harry Potter</Fullname>

</Contact>


<Customer><Firstname>

Harry</Firstname><Surname>

Potter</Surname>

</Customer>

Target MessageMappingSource Message

concat propertiesDelimiter=“ “

Simple Standard Functions: Substring




Function category: Text

counting starts at 0 !

Substring properties

start from: 0count: 10


<Customer><CustomerID>

0123456789</customerID>

</Customer >


<Contact><RefNo>0123456789-181170</RefNo >

</Contact >


Simple Standard Functions: DateTrans




Function category: Date


<Contact><birthday>

11/18/1970</birthday>

</Contact>


<Customer><custBirthday>

181170</custBirthday>

</Customer>


DateTrans properties

src Format: ddMMyydst Format: MM/dd/yyyy

For potential date patterns, please see Java class

java.text.DateFormat

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 valueif condition is true

R = Y if X is true or 1

or no tag is produced

ifWithoutElse

if

Calculations




Function category: Arithmetic

Calculations (add, multiply, etc.) are performedwith Java float precision

Trailing zeros in result are truncated, e.g.: 4.2-0.2 = 4

To keep trailing zeros use FormatNum function


<Contact><debt>

90.00</debt>

</Contact>


<Customer><debt>

90</debt>

</Customer>


FormatNum propertiesNumber Format:

###,###,###.00

(For potential patterns, please see

Java class java.text.DecimalFormat)








Standard Functions

Element Cardinality

Context Handling


Examples



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 the last

source element is reiterated.

Element Cardinality – Fixed Occurrences(minOccurs=maxOccurs)




Exception: Nodes with fixed

occurrences (minOccurs=maxOccurs)

Nodes are automatically marked in

green. Mapping is not mandatory.

<minOccurs> Nodes are created

automatically.

For elements with fixed occurrences

the rules of mandatory elements are

applied

Element Cardinality – Repeating Elements(maxOccurs>1)




Mapping of Repeating Elementsand 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, <minOccurs>

target elements are created.

If minOccurs=0, 1 target elementis created.

Element Cardinality – Node Mapping




Mapping of non mandatoryNodes (minOccurs=0 )

If a non mandatory node

contains elements with

minOccurs>0 , these elements

become mandatory after their parent node is assigned.

Element Cardinality – Node Mapping (II)




Mapping of non mandatoryNodes (minOccurs=0 )

Assignment of elements is not

sufficient

Node has to be ‘created’ by

assigning a suitable sourcenode/element

Element Cardinality – Unique Target Mapping




Mapping from more than oneSource 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 anelement, right-click on the

object in the target structure

pane and select “Duplicate

Subtree”







Standard Functions

Element Cardinality

Context Handling

Value Mapping


Examples



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 handlechanges in the message

hierarchy.

Context Handling (II)




Why Queue Processing?

No size limitations for messages

Better runtime performance

Context changes have impact on:


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

Context Handling - “Display Queue” (I)




A tool to display queues:

1. Upload or create source

xml-document in test

mode2. Right-click on box

representing element or

function

3. Select “Show queue”

Context Handling - “Display Queue” (II) Example




Sender and Receiver Structure

Related Mapping

Context Handling - “Display 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

Context Handling - “Display Queue” (IV)




Initial and terminal

context change –

Not passed to theinternal queue

processing

Inner context change.

Represented internally byconstant 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

Context Handling - Node Functions – removeContexts(I)





<Test_In_Remove><item>A.one</item><item>A.two</item><item>A.three</item><item>B.one</item><item>B.two</item>

</Test_In_Remove


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

</header><header name="B">

<item>B.one</item><item>B.two</item>

</header></Test_Out_Remove>


With removeContexts

use removeContext() to delete the parent context of an

element

compare to function “Explicit Context Selection”

Context Handling - Node Functions – removeContexts (II)






<Test_In_Remove><item>A.one</item><item>A.two</item><item>A.three</item>

</Test_In_Remove>


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

</header><header name="B">

<item>B.one</item><item>B.two</item>

</header></Test_Out_Remove>

Without removeContexts

Context Handling - Node Functions – SplitByValue (I)

With li l





<Test_In_Split><new_context>

<item>one</item></new_context><new_context>

<item>two</item></new_context><new_context>

<item>three</item></new_context><new_context>

<item>four</item></new_context>

</Test_In_Split>


<Test_Out_Split><header><item>one</item><item>two</item><item>three</item><item>four</item>

</header></Test_Out_Split>


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 .

Context Handling - Node Functions – SplitByValue (II)





<Test_In_Split><new_context>

<item>one</item><item>two</item><item>three</item><item>four</item>

</new_context><new_context /><new_context /><new_context />

</Test_In_Split>


<Test_Out_Split><header><item>one</item><item>two</item><item>three</item><item>four</item>

</header></Test_Out_Split>


WithoutSplitByValue

Context Handling – Explicit Context Selection (I)

A f XI 2 0 SP3 th t t f d d l t




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:

XML representationMessage Type

Context Handling – Explicit Context Selection (II)

Explicit choice of contexts and resulting queues




Context

Resulting

Queue

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 :

Context Handling – Contexts not in pair

Comparing two contexts with




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.







Standard Functions

Element Cardinality

Node Functions

Value Mapping


Examples


Multi–Mapping

Mapping Template

Value Mapping (I) – FixValues




The FixValues functionprovides a simple generic

value mapping (or key

mapping) in the Integration

Repository

1. Use the standard functionConversions -> FixValues to

link source and target element

2. Double click to define

properties

Each field mapping uses itsown table of key-value pairs.

Filled tables can be copied to

other mappings. But copied

table is independent of origin.

Value Mapping (II) – Value mapping




The Value mapping functionprovides a more specific value

transformation.

1. Use the standard functionConversions -> Value mapping to

link source and target element2. 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 IntegrationDirectory, usehttp://sap.com/xi/XI

Agency and Schema for sender and

receiver messages. Any arbitrary

string value can be used.

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 group’s representative for a given Agency – Schema combination)

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.

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:







Standard Functions

Element Cardinality

Node Functions

Value Mapping


Examples


Multi–Mapping

Mapping Template

User-Defined Functions – Overview




Functional enhancements if standardfunctions 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

User-Defined Functions – Overview




User–Defined Function types: Simple functions,

process individual field input values for each function call.

expect strings as input values

return a string.

Advanced functions,

process non–single string field input values for each

function callpass either all field values of a context or the whole queue

input field is passed as string array

returned values are stored in a string array, ResultList

User-Defined Functions – Definition (I)




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 typejava.lang.String

Description:Description of the function’s use.

User-Defined Functions – Definition (II)




Create NewFunction

User-Defined Functions – Definition (III)




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.*;

User-Defined Functions – Binding of external Classes (I)

Example: following class should enhance a user-defined function




com.sap.aii.mappingtool.tf3.rt.Container

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 Importstatement

Advanced user–defined functions can access more than just individual

al es A complete conte t or an entire q e e can be accessed

User-Defined Functions – Advanced Functions (I)




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.

ContextQueue

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

complete queue into input String arrays

User-Defined Functions – Advanced Functions (II)




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

Contains context change indicator. Much more

memory intensive.

Queue

Do not have identifiable context change.Context

ImplicationsInformation in Cache

Context changes at the beginning and end of the queue are implicit and areskipped

User-Defined Functions – Advanced Functions (III)




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

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




Queue output determines input values of user-defined functions

First and last context change of each queue are suppressed

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",ResultList.CC,"A.2.1",ResultList.CC,"A.3.1",ResultList.CC,"B.1.1",ResultList.CC,"B.2.1","B.2.2"};

Caching the whole queue Not caching the whole queue

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.1"};{"A.3.1"};{"B.1.1"};{"B.2.1","B.2.2"};

User-defined functions – function types




Function is called once per

context or queue. Values of

context /queue are stored in

input string arrays

Function is called once per

occurrence of the source

element

Processing

result.addValue(String);return String;Returning

Values

String[], …, ResultList,Container

String, …, ContainerInput

Parameters

Advanced FunctionsSimple Functions

User-defined functions – Container

Container supports the methods

void setParamter(String, Object) Obj t tP t (St i )




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 messagemapping

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

User-defined functions – ResultList

ResultList supports the methods and constants




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.








Standard Functions

Element Cardinality

Node Functions

Value Mapping


Examples


Multi–Mapping

Mapping Template

Examples – Get value by key (I)

Problem:




Problem: A specific value should be filtered by a key or qualifier

Example: only English <TEXT> should be mapped to resulting field

<Description>

Examples– Get value by key (II)

Solution:




2. Set Contexts of <LANGKEY> and

<TEXT>

1. Create mapping

Solution:

Examples– Get value by key (III)

3. Display Queues

Discussion:




Since the element <Description> may only occur once in the

resulting structure, the output has to be put in a single context. Thetwo suppressed values are removed automatically when the

resulting document is created

In an alternative solution two contexts of <LANGKEY> and <TEXT>keep their initial contexts and a removeContexts is inserted after

the ifWithoutElse function.

4. Explanation

to investigate

Examples – Copy head to line (I)

Problem: A hierarchical structure has to be mapped to a flat structure




Problem: A hierarchical structure has to be mapped to a flat structure

One <row> should be created per <Item>

Header information (represented <Header>) occurring only once per <Order> should be multiplied and copied to <row>.

Examples – Copy head to line (II)

1. Create User-

Solution:




2. Create

mappings

1. Create User

Defined Function

Examples – Copy head to line (III)

3. Display Queues

Discussion:




The User-Defined Function copyPerValue copies the value of

<Address> per each occurrence of <Item> to the relevant context.The SplitByValue function then distributes the copied values to

the contexts of the flat structure.

Since <Item> only contains empty fields, you can use in this casealso function concat instead of copyPerValue. See Context

Handling – Explicit Context Selection (I) for details.

4. Explanation

3. Display Queues






pp g


Standard Functions

Element Cardinality

Node Functions

Value Mapping


Examples


Multi–Mapping

Mapping Template


Mapping “patterns” are some of the common mapping

requirements we found in the past which XSLT was used, becausedid t thi k th t M M i id d th f ti lit




we did not think that Message Mapping provided the functionality

Summarization Sequence–Number Generation

Duplicating Subtrees

Table / Value Lookups

Tree–Reversal

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

t b i d t b l t d i t l

Mapping “Patterns” – Summarization (I)




group to be summarized must be selected appropriately.

Example:

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



Mapping “Patterns” – Summarization (III)

Mapping Result:




Mapping “Patterns” – Sequence–Number Generation (I)

There are situations when sequence numbers had to be generated based

on the number of occurrences of the source data. This is frequently usedduring mapping to SAP IDocs or BAPIs when item number, which is no




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 asequence number which matches

the position of the data in the

source.

Sequence number to be generated.

Mapping “Patterns” – Sequence–Number Generation (II)

There are two ways the sequence number can be generated.

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




U U g q

number all at once.

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

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

Mapping “Patterns” – Sequence–Number Generation (III)


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.

Mapping “Patterns” – Sequence–Number Generation (IV)


number all at once.




Mapping “Patterns” – Sequence–Number Generation (V)


number all at once.

Test Results:




Test Results:

Mapping “Patterns” – Sequence–Number Generation (VI)

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

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




The sequence number is stored in

the container object. Each time it

is retrieved, incremented and

saved.

Note: There is no input required.

Mapping “Patterns” – Sequence–Number Generation (VII)






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

Mapping “Patterns” – Sequence–Number Generation (VIII)






Mapping “Patterns” – Duplicating Subtrees (I)

Even if elements are shown to occur more than once in the XML instance according

to XML Schema Definition, they are only displayed once in the structure overview.

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




the element or the entire subree can be duplicated (copied) using the context menu

in the target structure.

Example:

Source: Accounting information with

adjustment type and amount.

Target: Two CurrencyAmt’s are to

be created. One is to credit one

account. The other is to debitanother account. The amount will

either be positive or negative

depending on the ADJTYPE.

Mapping “Patterns” – Duplicating Subtrees (II)

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

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




Mapping “Patterns” – Duplicating Subtrees (III)




Mapping “Patterns” – Duplicating Subtrees (IV)

Mapping Results:




Mapping “Patterns” – Table/Value Lookup (I)

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 cannavigate 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, sub–account, 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, sub–account 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.

Mapping “Patterns” – Table/Value Lookup (II)

Source: Target:




=

Mapping “Patterns” – Table/Value Lookup (III)

Java Function:




The lookup’d value

must be written to the

ResultList.

Mapping “Patterns” – Table/Value Lookup (IV)




Mappings for all 3 elements are identical, except for the element names.

Contexts must be set a root level.

Mapping “Patterns” – Table/Value Lookup (V)

Mapping Results:




Mapping “Patterns” – Tree–Reversal (I)

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

ORDERID

listed.

Mapping “Patterns” – Tree–Reversal (II)

The source document is organized by ORDERID, ITEM 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




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.

Mapping “Patterns” – Tree–Reversal (III)

Three Java functions were written to:

1. Extract the products, eliminate duplicate names, and sort them in alphabetical order.




Mapping “Patterns” – Tree–Reversal (IV)

2. Total the prices and assign the total to the appropriate products.




Mapping “Patterns” – Tree–Reversal (V)

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.

Mapping “Patterns” – Tree–Reversal (VI)

Mapping for ITEM: To create the number of elements.




Mapping “Patterns” – Tree–Reversal (VII)

Mapping for the attribute NAME, which is the product name.




Mapping “Patterns” – Tree–Reversal (VIII)

Display Queue for determining NAME:




Mapping “Patterns” – Tree–Reversal (IX)

Mapping to create the number of element for ORDERS_WHERE_ITEM_IS_FOUND.




Mapping “Patterns” – Tree–Reversal (X)

Mapping for the attribute TotalSalesFOrThisItem, which totals the prices by product name.




Mapping “Patterns” – Tree–Reversal (XI)

Display Queue for determining TotalSalesFOrThisItem:




Mapping “Patterns” – Tree–Reversal (XII)

Mapping for the element ORDERID, which will be listed by product name.



©SAP AG 2002, Title of Presentation, Speaker Name 136

Mapping “Patterns” – Tree–Reversal (XIII)

Display Queue for determining ORDERID:




Mapping “Patterns” – Tree–Reversal (XIV)

Partial listing of the mapping results:





Mapping – Introduction Message Mapping

G l C t




General Concepts

Standard Functions Element Cardinality

Node Functions

Value Mapping

User-Defined Functions Examples


Multi–Mapping

Mapping Template

Multi–Mappings

Multi–Mapping 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 TransformationSplits a message into multiple messages, for example, a purchase order intothe individual purchase order items.

n:m Transformation

Converts a message into another message, for example, a message that isdefined by interface A is converted to message that is defined by interface B.

Multi–Mappings 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.

Mapping “Patterns” – Multi–Mappings

The Message Types are entered using the Messages tab in the mapping editor.

The root element is always <Messages>.

The Mapping Editor inserts an element <MessageN> for each source or target message, where Nis the position of the message.

Example:

Order (1)OrderHeader (1)

Message Type (Target)Message Type (Source)




OrderInfo (1)OrderItem (0…unbounded)

Mapping “Patterns” – Multi–Mappings

1. Insert more2. Change




messages2. Change

Occurrences

No msg

type

name

Mapping rules are the same as for previously discussed Message Mappings.







General Concepts

Standard Functions

Element Cardinality

Node Functions

Value Mapping

User-Defined Functions Examples


Multi–Mapping

Mapping Template

Mapping Templates (I)

Mappings based on Data Types 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.

Mapping Templates (II)

The Mapping Editor is used to create and load the structures used by theMapping 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




pp g p gfrom the menu bar

3. Enter a unique name for the new Mapping Template.

Mapping Templates (III)

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.

Further Information

Public Web:

http://help.sap.comhttp://sdn.sap.com

http://service.sap.com

SAP C t S i N t k htt // / i /




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

Questions?




Q&A

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.

Microsoft®, WINDOWS®, NT®, EXCEL®, Word®, PowerPoint® and SQL Server® are registered trademarks of

Microsoft Corporation.

IBM®, DB2®, DB2 Universal Database, OS/2®, Parallel Sysplex®, MVS/ESA, AIX®, S/390®, AS/400®, OS/390®,

Copyright 2004 SAP AG. All Rights Reserved




OS/400®, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere®, Netfinity®, Tivoli®,

Informix and Informix® Dynamic ServerTM are trademarks of IBM Corporation in USA and/or other countries. ORACLE® is a registered trademark of ORACLE Corporation.

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.

MarketSet and Enterprise Buyer are jointly owned trademarks of SAP AG and Commerce One.

SAP, SAP Logo, R/2, R/3, mySAP, mySAP.com and other SAP products and services mentioned herein as well astheir respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other

countries all over the world. All other product and service names mentioned are trademarks of their respective

companies.

Weitergabe und Vervielfältigung dieser Publikation oder von Teilen daraus sind, zu welchem Zweck und in welcher Form auch immer, ohne die ausdrückliche schriftliche Genehmigung durch SAP AG nicht gestattet. In dieser Publikation enthaltene Informationen können ohne vorherige Ankündigung geändert werden.

Die von SAP AG oder deren Vertriebsfirmen angebotenen Softwareprodukte können Softwarekomponenten auchanderer Softwarehersteller enthalten.

Microsoft®, WINDOWS®, NT®, EXCEL®, Word®, PowerPoint® und SQL Server® sind eingetragene Marken der Microsoft Corporation.

IBM®, DB2®, DB2 Universal Database, OS/2®, Parallel Sysplex®, MVS/ESA, AIX®, S/390®, AS/400®, OS/390®,

Copyright 2004 SAP AG. Alle Rechte vorbehalten




OS/400®, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere®, Netfinity®, Tivoli®,

Informix und Informix® Dynamic ServerTM sind Marken der IBM Corporation in den USA und/oder anderenLändern.

ORACLE® ist eine eingetragene Marke der ORACLE Corporation.

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

Citrix®, das Citrix-Logo, ICA®, Program Neighborhood®, MetaFrame®, WinFrame®, VideoFrame®, MultiWin® undandere hier erwähnte Namen von Citrix-Produkten sind Marken von Citrix Systems, Inc.

HTML, DHTML, XML, XHTML sind Marken oder eingetragene Marken des W3C®, World Wide Web Consortium,Massachusetts Institute of Technology.

JAVA® ist eine eingetragene Marke der Sun Microsystems, Inc.

JAVASCRIPT® ist eine eingetragene Marke der Sun Microsystems, Inc., verwendet unter der Lizenz der vonNetscape entwickelten und implementierten Technologie.

MarketSet und Enterprise Buyer sind gemeinsame Marken von SAP AG und Commerce One.

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

mapping functional it yin xi

Documents