Session ID: XI302 SAP Exchange Infrastructure – Graphical Mapping – Advanced
Feb 08, 2016
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
© SAP AG 2004, SAP TechEd / XI302 / 5
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
© SAP AG 2004, SAP TechEd / XI302 / 6
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
Message MappingXSLT MappingJava Mapping
ABAP Mapping
OutputMessage Type
Message MappingXSLT MappingJava Mapping
ABAP Mapping
Overview – Relate Mapping Programs to Interfaces
© SAP AG 2004, SAP TechEd / XI302 / 7
Integration Builder: Introduction
© SAP AG 2004, SAP TechEd / XI302 / 8
Data-Flow Editor
Structure Overview
Source Structure Target Structure
Target Field Mapping
General Concepts – Mapping Editor (I)
© SAP AG 2004, SAP TechEd / XI302 / 9
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)
© SAP AG 2004, SAP TechEd / XI302 / 10
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
© SAP AG 2004, SAP TechEd / XI302 / 11
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
User-defined Functions
Introduction to Message Mapping
Element Cardinality
© SAP AG 2004, SAP TechEd / XI302 / 13
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.
© SAP AG 2004, SAP TechEd / XI302 / 14
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
© SAP AG 2004, SAP TechEd / XI302 / 15
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)
© SAP AG 2004, SAP TechEd / XI302 / 16
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 2004, SAP TechEd / XI302 / 17
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 2004, SAP TechEd / XI302 / 18
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
User-defined Functions
Introduction to Message Mapping
Element Cardinality
© SAP AG 2004, SAP TechEd / XI302 / 20
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 2004, SAP TechEd / XI302 / 21
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 2004, SAP TechEd / XI302 / 22
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”
© SAP AG 2004, SAP TechEd / XI302 / 23
Context Handling – “Display Queue” (II) Example
Sender and Receiver Structure
Related Mapping
© SAP AG 2004, SAP TechEd / XI302 / 24
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
© SAP AG 2004, SAP TechEd / XI302 / 25
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
© SAP AG 2004, SAP TechEd / XI302 / 26
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
<?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>
Target MessageMappingSource Message
With removeContexts
use removeContext() to delete the parent context of an element
compare to function “Explicit Context Selection”
© SAP AG 2004, SAP TechEd / XI302 / 27
Context Handling – Node Functions – removeContexts (II)
Target MessageMappingSource 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>
<?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>
Without removeContexts
© SAP AG 2004, SAP TechEd / XI302 / 28
<?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>
<?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>
Target MessageMappingSource Message
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 2004, SAP TechEd / XI302 / 29
<?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>
<?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>
Target MessageMappingSource Message
Context Handling – Node Functions – SplitByValue (II)
Without SplitByValue
© SAP AG 2004, SAP TechEd / XI302 / 30
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
© SAP AG 2004, SAP TechEd / XI302 / 31
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 :
© SAP AG 2004, SAP TechEd / XI302 / 32
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
User-defined Functions
Introduction to Message Mapping
Element Cardinality
© SAP AG 2004, SAP TechEd / XI302 / 34
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 2004, SAP TechEd / XI302 / 35
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
© SAP AG 2004, SAP TechEd / XI302 / 36
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.
© SAP AG 2004, SAP TechEd / XI302 / 37
Create New Function
User-Defined Functions – Definition (II)
© SAP AG 2004, SAP TechEd / XI302 / 38
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)
© SAP AG 2004, SAP TechEd / XI302 / 39
Example: following class should enhance a user-defined function
com.sap.aii.mappingtool.tf3.rt.Container
User-Defined Functions – Binding of external Classes (I)
© SAP AG 2004, SAP TechEd / XI302 / 40
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)
© SAP AG 2004, SAP TechEd / XI302 / 41
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)
© SAP AG 2004, SAP TechEd / XI302 / 42
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)
© SAP AG 2004, SAP TechEd / XI302 / 43
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
© SAP AG 2004, SAP TechEd / XI302 / 44
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[]
© SAP AG 2004, SAP TechEd / XI302 / 45
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
© SAP AG 2004, SAP TechEd / XI302 / 46
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
© SAP AG 2004, SAP TechEd / XI302 / 47
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
User-defined Functions
Element Cardinality
Summary
© SAP AG 2004, SAP TechEd / XI302 / 50
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
© SAP AG 2004, SAP TechEd / XI302 / 51
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 AG 2004, SAP TechEd / XI302 / 52
SAP Developer Network
Look for SAP TechEd ’04 presentations and videos on the SAP Developer Network.
Coming in December.
http://www.sdn.sap.com/
© SAP AG 2004, SAP TechEd / XI302 / 53
Q&A
Questions?
© SAP AG 2004, SAP TechEd / XI302 / 54
Please complete your session evaluation.
Be courteous — deposit your trash, and do not take the handouts for the following session.
Feedback
Thank You !
© SAP AG 2004, SAP TechEd / XI302 / 55
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