SAP Exchange Infrastructure - Graphical Mapping - Advanced

Session ID: XI302 SAP Exchange Infrastructure Graphical Mapping Advanced
William Li, SAP Labs, LLC. Joachim Orb, SAP AG
Introduction to Message Mapping Element Cardinality Context Handling User-defined Functions
Concepts General Mapping Types

Mapping
Transformation from one message structure to another Transformation of one key value to another
<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>
Value Mapping
<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>
Structure Mapping
SAP AG 2004, SAP TechEd / XI302 / 4
Mapping at Runtime
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)
Integration Server
Inbound Handling (also in adapters) Receiver Determination Interface Determination Channel Determination Mapping Outbound Handling (also in adapters)
1
Business Process Execution
1;2
Business Process Engine
Integration Engine
Overview Relate Mapping Programs to Interfaces

Outbound Message Interface
Integration Repository
Interface Mapping(s)
Message Mapping XSLT Mapping Java Mapping ABAP Mapping
Inbound Message Interface
Request Response Fault
Output Message Type
Input Message Type
Input Message Type
Output Message Type
Fault Message Type
Fault Message Type
Integration Builder: Introduction
General Concepts Mapping Editor (I)
Structure Overview
Source Structure
Target Structure
Data-Flow Editor Target Field Mapping
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
Icon Status Display

Icon Types
Icon Meaning Attribute Element Element with maxOccurs = unbounded Node
Icon Colors
Color White Red
Yellow
Meaning Attribute or element not assigned Attribute or element must be assigned to complete the mapping 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

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.
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 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 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 (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 xmldocument 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 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
Context Handling Node Functions removeContexts(I) With removeContexts

Source Message
<?xml version="1.0" encoding="UTF-8" ?> <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>
Mapping
Target Message
<?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
use removeContext() to delete the parent context of an element compare to function Explicit Context Selection
Context Handling Node Functions removeContexts (II)

Without removeContexts
Source Message
<?xml version="1.0" encoding="UTF-8" ?> <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>
Mapping
Target Message
<?xml version="1.0" encoding="UTF-8" ?> <Test_In_Remove> <item>A.one</item> <item>A.two</item> <item>A.three</item> </Test_In_Remove>
Context Handling Node Functions SplitByValue (I)

With SplitByValue
Source Message
<?xml version="1.0" encoding="UTF-8" ?> <Test_Out_Split> <header> <item>one</item> <item>two</item> <item>three</item> <item>four</item> </header> </Test_Out_Split>
Mapping
Target Message
<?xml version="1.0" encoding="UTF-8" ?> <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>
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)

Without SplitByValue
Source Message
<?xml version="1.0" encoding="UTF-8" ?> <Test_Out_Split> <header> <item>one</item> <item>two</item> <item>three</item> <item>four</item> </header> </Test_Out_Split>
Mapping
Target Message
<?xml version="1.0" encoding="UTF-8" ?> <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>
Context Handling Explicit Context Selection (I)

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: Message Type XML representation
Context Handling Explicit Context Selection (II)

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
Resulting Queue
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.
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 UserDefined Function types:

Simple functions, process individual field input values for each function call. expect strings as input values return a string. Advanced functions, process nonsingle 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 functions use.
User-Defined Functions Definition (II)
Create New Function
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:

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 Advanced Functions (I)

Advanced userdefined functions can access more than just individual values. A complete context or an entire queue can be accessed.
Context
Queue
Message Mapping works by using queues. There is a queue for each hierarchy level.
User-Defined Functions Advanced Functions (II)

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 Context Queue Implications Do not have identifiable context change. Contains context change indicator. Much more memory intensive.
Context changes at the beginning and end of the queue are implicit and are skipped
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 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"};
User-defined functions function types
Simple Functions
Input Parameters String, , Container
Advanced Functions
String[], , ResultList, Container
Returning Values
return String;
result.addValue(String);
Processing
Function is called once per occurrence of the source element
Function is called once per context or queue. Values of context /queue are stored in input string arrays
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
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.
Element Cardinality Context Handling User-defined Functions
Summary
Summary
Now you should know: about the impact of message structure on mapping whats meant by contexts in Message Mapping and how to handle them how to develop user-defined functions
Further Information
Public Web:
www.sap.com SAP Developer Network: www.sdn.sap.com Exchange Infrastructure SAP Customer Services Network: www.sap.com/services/
Related SAP Education Training Opportunities

http://www.sap.com/education/
Related Workshops/Lectures at SAP TechEd 2004

XI253, SAP Exchange Infrastructure - Graphical Mapping - Introduction
SAP Developer Network

Look for SAP TechEd 04 presentations and videos on the SAP Developer Network. Coming in December. http://www.sdn.sap.com/
Questions?
Q&A
Feedback
Please complete your session evaluation. Be courteous deposit your trash, and do not take the handouts for the following session.
Thank You !
Copyright 2004 SAP AG. All Rights Reserved

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. 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.

SAP Exchange Infrastructure - Graphical Mapping - Advanced

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

SAP Exchange Infrastructure - Graphical Mapping - Advanced

Загружено:

Авторское право:

Доступные форматы

Session ID: XI302 SAP Exchange Infrastructure Graphical Mapping Advanced

William Li, SAP Labs, LLC. Joachim Orb, SAP AG

Introduction to Message Mapping Element Cardinality Context Handling User-defined Functions

Concepts General Mapping Types

SAP AG 2004, SAP TechEd / XI302 / 4

Business Process Engine

Overview Relate Mapping Programs to Interfaces

Inbound Message Interface

Request Response Fault

Output Message Type

Input Message Type

Input Message Type

Message Mapping XSLT Mapping Java Mapping ABAP Mapping

Output Message Type

Fault Message Type

Message Mapping XSLT Mapping Java Mapping ABAP Mapping

Fault Message Type

SAP AG 2004, SAP TechEd / XI302 / 6

Integration Builder: Introduction

SAP AG 2004, SAP TechEd / XI302 / 7

General Concepts Mapping Editor (I)

Data-Flow Editor Target Field Mapping

SAP AG 2004, SAP TechEd / XI302 / 8

General Concepts Mapping Editor (II)

From local file system (XSD or XML)

SAP AG 2004, SAP TechEd / XI302 / 9

Icon Status Display

Green Mapping to target field complete

General Concepts Debug Mappings

SAP AG 2004, SAP TechEd / XI302 / 11

Introduction to Message Mapping Element Cardinality Context Handling User-defined Functions

Element Cardinality Mandatory Mappings

Mandatory Elements and Nodes (minOccurs>0)

SAP AG 2004, SAP TechEd / XI302 / 13

Element Cardinality Fixed Occurrences

Exception: Nodes with fixed occurrences (minOccurs=maxOccurs)

SAP AG 2004, SAP TechEd / XI302 / 14

Element Cardinality Repeating Elements

Mapping of Repeating Elements and Nodes (maxOccurs>1)

SAP AG 2004, SAP TechEd / XI302 / 15

Element Cardinality Node Mapping

Mapping of non mandatory Nodes (minOccurs=0)

SAP AG 2004, SAP TechEd / XI302 / 16

Element Cardinality Node Mapping (II)

Mapping of non mandatory Nodes (minOccurs=0)

SAP AG 2004, SAP TechEd / XI302 / 17

Element Cardinality Unique Target Mapping

Mapping from more than one Source element

SAP AG 2004, SAP TechEd / XI302 / 18

Introduction to Message Mapping Element Cardinality Context Handling User-defined Functions

Context Handling (I)

SAP AG 2004, SAP TechEd / XI302 / 20

Context Handling (II)

Context changes have impact on:

Manipulation of queues ant contexts

Context Handling Display Queue (I)

SAP AG 2004, SAP TechEd / XI302 / 22

Context Handling Display Queue (II) Example

SAP AG 2004, SAP TechEd / XI302 / 23

Context Handling Display Queue (III) Example

Context Handling Display Queue (IV)

Inner context change. Represented internally by constant ResultList.CC

The displayed queue contains the following values:

ResultList.SUPPRESS ResultList.CC toothpaste ResultList.CC ResultList.SUPPRESS

Import Java packages if required, e.g. sap.xi.mytools.; sap.xi.myutils.;