sap exchange infrastructure - graphical mapping - advanced

Session ID: XI302SAP Exchange Infrastructure –Graphical Mapping –Advanced

William Li, SAP Labs, LLC.

Joachim Orb, SAP AG

Context Handling

User-defined Functions

Introduction to Message Mapping

Element Cardinality

© SAP AG 2004, SAP TechEd / XI302 / 4

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

<hh:first-name>Micheal</hh:first-name><hh:surname>Moore</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>Micheal Moore</ak:Passenger><ak:Class>2</ak:Class><ak:Agency>Happy Holiday</ak:Agency>

</ak:BookFlight>

Mapping

Transformation from one message structure to another

Transformation of one key value to another

Structure Mapping

Value Mapping

Concepts – General Mapping Types


Integration Server

Business ProcessEngine

Mapping at Runtime

IntegrationEngine

Outbound Handling(also in adapters)

Business ProcessExecution

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


Interface Mapping(s)

Integration Repository

Req

uest

Fau

lt

FaultMessage Type

InboundMessage Interface

FaultMessage Type

OutboundMessage Interface

Input Message Type

Resp

on

se

InputMessage Type

OutputMessage Type

Message MappingXSLT MappingJava Mapping

ABAP Mapping


ABAP Mapping

OutputMessage Type


ABAP Mapping

Overview – Relate Mapping Programs to Interfaces


Integration Builder: Introduction


Data-Flow Editor

Structure Overview

Source Structure Target Structure

Target Field Mapping

General Concepts – Mapping Editor (I)


Import of source and target structureFrom 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 (II)


Icon Status Display

Element with maxOccurs = unbounded

MeaningIcon

Node

Element

Attribute

Icon Types

Icon Colors

Mapping to target field complete Green

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

MeaningColor


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.

Context Handling



Element Cardinality


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


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, <minOccurs> target elements are created.

If minOccurs=0, 1 target element is created.

Element Cardinality – Repeating Elements(maxOccurs>1)


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.


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


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”

Context Handling



Element Cardinality


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.


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


Context Handling – “Display Queue” (I)

A tool to display queues:

Upload or create source xml-document in test mode

Right-click on box representing element or function

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 queueprocessing

Inner context change. Represented internally byconstant ResultList.CC

Queue value

Suppressed value. Represented internally byconstant

ResultList.SUPPRESS. Suppressed when creating target element

The displayed queue contains thefollowing values:

ResultList.SUPPRESSResultList.CC“toothpaste”ResultList.CCResultList.SUPPRESS


Context Handling – Node Functions – removeContexts(I)

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

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

Target MessageMappingSource Message

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



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


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.



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


Context Handling – Node Functions – SplitByValue (II)

Without SplitByValue


Context Handling – Explicit Context Selection (I)

As of XI 2.0 SP3 the context of source nodes and elements can be selected explicitlyMore 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)

Context

ResultingQueue

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

Context Handling



Element Cardinality


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


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 call

pass 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 type java.lang.String

Description:Description of the function’s use.


Create New Function

User-Defined Functions – Definition (II)


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 – Definition (III)


Example: following class should enhance a user-defined function

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

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


Procedure:

Compile your Java class and create a .jar

Create a new Imported Archive and upload your .jar.

The relevant class has to be declared in the Import statement

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


Advanced user–defined 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.

ContextQueue

User-Defined Functions – Advanced Functions (I)


Advanced user–functions can import either just one context or the complete queue into input String arrays.

To import the complete queue, check the “Cache Entire Queue” checkbox in the function editor.

Working with Contexts or Queues

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

User-Defined Functions – Advanced Functions (II)


User-Defined Functions – Advanced Functions (III)

Input parameters: String[] , ResultList, ContainerFlag “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


Context changes are treated as fields

They are represented by class variable java.lang.String ResultList.CCQueue 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 – String[]


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 sourceelement

Processing

result.addValue(String);return String;ReturningValues

String[], …, ResultList, Container

String, …, ContainerInput Parameters

Advanced FunctionsSimple Functions


User-defined functions – Container

Container supports the methodsvoid setParamter(String, Object)Object getParameter(String)

Stalled parameters can be accessed in this specific functionGlobalContainer getGlobalContainer()MappingTrace getTrace()Map getTransformationParameters()

Map can be used to get runtime constants, e.g.Object map.get(StreamTransformationConstants.SENDER_SYSTEM)

GlobalContainer supports the methodsvoid setParamter(String, Object)Object getParameter(String)

Stalled parameters can be accessed in different functions of one messagemapping

MappingTrace supports the methodsvoid addWarning(String) – trace level: 1, 2, 3void addInfo(String) – trace level: 2, 3void addDebugMessage(String)– trace level: 3

Writes String to message monitoring


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.

Context Handling


Element Cardinality

Summary


Now you should know:

about the impact of message structure on mapping

what’s meant by contexts in Message Mapping and how to handle them

how to develop user-defined functions

Summary


Public Web:www.sap.com

SAP Developer Network: www.sdn.sap.com Exchange Infrastructure

SAP Customer Services Network: www.sap.com/services/

Related Workshops/Lectures at SAP TechEd 2004XI253, SAP Exchange Infrastructure - Graphical Mapping - Introduction

Related SAP Education Training Opportunitieshttp://www.sap.com/education/

Further Information


SAP Developer Network

Look for SAP TechEd ’04 presentations and videos on the SAP Developer Network.

Coming in December.

http://www.sdn.sap.com/


Q&A

Questions?


Please complete your session evaluation.

Be courteous — deposit your trash, and do not take the handouts for the following session.

Feedback

Thank You !


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, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation.

IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere, Netfinity, Tivoli, and Informix are trademarks or registered trademarks of IBM Corporation in the United States 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, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc.

HTML, XML, XHTML and W3C 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.

MaxDB is a trademark of MySQL AB, Sweden.

SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary.

These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

Copyright 2004 SAP AG. All Rights Reserved

sap exchange infrastructure - graphical mapping - advanced

Documents

sap teched xi302

sap labs

introduction sap ag

whitemeaningcolor sap

mapping programs

mapping step

mapping redattribute

corresponding mapping