Bit460 en Col95 Fv Part a4 Notes(2)

For internal use by CSC only

PI Message Mapping SAP NetWeaver Process Integration

Date Training Center Instructors

Education Website

Participant Handbook Course Version: 95 Course Duration: 2 Day(s) Material Number: 50102743

An SAP course - use it to learn, reference it for work


BIT460

Copyright Copyright © 2011 SAP AG. All rights reserved.

Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors.

Trademarks •

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

•

IBM®, DB2®, OS/2®, DB2/6000®, Parallel Sysplex®, MVS/ESA®, RS/6000®, AIX®, S/390®, AS/400®, OS/390®, and OS/400® are registered trademarks of IBM Corporation.

•

ORACLE® is a registered trademark of ORACLE Corporation.

•

INFORMIX®-OnLine for SAP and INFORMIX® Dynamic ServerTM are registered trademarks of Informix Software Incorporated.

•

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.

•

SAP, SAP Logo, R/2, RIVA, R/3, SAP ArchiveLink, SAP Business Workflow, WebFlow, SAP EarlyWatch, BAPI, SAPPHIRE, Management Cockpit, mySAP.com Logo and mySAP.com are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other products mentioned are trademarks or registered trademarks of their respective companies.

Disclaimer THESE MATERIALS ARE PROVIDED BY SAP ON AN "AS IS" BASIS, AND SAP EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES, EXPRESS OR APPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THESE MATERIALS AND THE SERVICE, INFORMATION, TEXT, GRAPHICS, LINKS, OR ANY OTHER MATERIALS AND PRODUCTS CONTAINED HEREIN. IN NO EVENT SHALL SAP BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES OF ANY KIND WHATSOEVER, INCLUDING WITHOUT LIMITATION LOST REVENUES OR LOST PROFITS, WHICH MAY RESULT FROM THE USE OF THESE MATERIALS OR INCLUDED SOFTWARE COMPONENTS.

g2011421568



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.

About This Handbook For internal use by CSC only

Typographic Conventions American English is the standard used in this handbook. The following typographic conventions are also used. Type Style

Description

Example text

Words or characters that appear on the screen. These include field names, screen titles, pushbuttons as well as menu names, paths, and options. Also used for cross-references to other documentation both internal and external.

2011

Example text

Emphasized words or phrases in body text, titles of graphics, and tables

EXAMPLE TEXT

Names of elements in the system. These include report names, program names, transaction codes, table names, and individual key words of a programming language, when surrounded by body text, for example SELECT and INCLUDE.

Example text

Screen output. This includes file and directory names and their paths, messages, names of variables and parameters, and passages of the source text of a program.

Example text

Exact user entry. These are words and characters that you enter in the system exactly as they appear in the documentation.

Variable user entry. Pointed brackets indicate that you replace these words and characters with appropriate entries.

© 2011 SAP AG. All rights reserved.

iii


This handbook is intended to complement the instructor-led presentation of this course, and serve as a source of reference. It is not suitable for self-study.

About This Handbook

BIT460

Icons in Body Text The following icons are used in this handbook.


Meaning For more information, tips, or background

Note or further explanation of previous point Exception or caution Procedures

Indicates that the item is displayed in the instructor's presentation.

iv


2011


Icon

Course Overview ......................................................... vii Course Goals ...........................................................vii Course Objectives .....................................................vii

Unit 1: Creating an Operations Mapping ............................. 1 Creating an Operation Mapping.......................................2

Unit 2: Mapping Messages ............................................ 17 Creating a Message Mapping ....................................... 18 Testing a Message Mapping......................................... 32 Using Message-Mapping Functions ................................ 50

Unit 3: Advanced Mapping Concepts ............................... 65 Using Contexts in Message Mapping .............................. 66 Working with User-Defined Functions.............................. 88

Unit 4: Advanced Functions.......................................... 135 Using Parameters in Mapping Programs .........................136 Working with Value Mapping functions............................147 Mapping Multiple Messages ........................................173 Creating a Message-Mapping Template ..........................178

Unit 5: Other Mapping Types......................................... 189 Importing and Using XSLT Mapping...............................190 Creating a Java Mapping ...........................................200

2011


v



Contents

Contents

BIT460



vi


2011



Course Overview Target Audience This course is intended for the following audiences: Consultants and developers who configure scenarios for SAP NetWeaver Process Integration in which mappings are required.

•

Course Prerequisites Required Knowledge •

BIT400 (SAP NetWeaver Process Integration)

Recommended Knowledge •

JA100 (SAP J2SE Fundamentals)

Course Goals This course will prepare you to: • •

Create, test, and use message mappings Use advanced features of message mappings

Course Objectives After completing this course, you will be able to: • •

Create, test, and use message mappings Use advanced features of mapping types

SAP Software Component Information The information in this course pertains to the following SAP Software Components and releases: •

2011

SAP NetWeaver Process Integration 7.3


vii

Course Overview

BIT460



viii


2011


Creating an Operations Mapping Unit Overview This short introductory unit introduces general mapping tasks and discusses operation mappings.

Unit Objectives After completing this unit, you will be able to: • • •

Create an Operation Mapping Check the inbound and outbound service interfaces List the available mapping program types for PI

Unit Contents Lesson: Creating an Operation Mapping .......................................2 Exercise 1: Create an Operation Mapping .................................9

2011


1


Unit 1

Unit 1: Creating an Operations Mapping

BIT460

Lesson: Creating an Operation Mapping Lesson Overview For internal use by CSC only

Lesson Objectives After completing this lesson, you will be able to: • • •

Create an Operation Mapping Check the inbound and outbound service interfaces List the available mapping program types for PI

Business Example You are responsible for creating Operation Mappings and need to understand the types of mapping programs that can be used in an Operation Mapping in SAP NetWeaver Process Integration (PI).

About PI Mapping SAP NetWeaver Process Integration mediates the message transfer between sender and receiver systems, and in most cases these systems use different interfaces. Thus, PI has to perform a mapping between the outbound interface of the sender and the inbound interface of the receiver interface (or interfaces). Concepts to be applied in mapping are: •

Structure mapping You must define mapping rules to assign fields that are semantically identical.

•

Value mapping You must define conversion rules to transfer the field content to the target format.

The figure Concepts Implemented in Mapping details both of these concepts. Firstly, the source message and the target message each have their own individual structures. These differing structures require a structure mapping. Secondly, the value business of the source field class has to be transformed into the value 2 in the Class target field, using a value mapping.

2


2011


This lesson shows you how to create an operation mapping to connect operations from service interfaces with one another. The lesson also introduces general mapping tasks, and provides an overview of mapping program types.

Lesson: Creating an Operation Mapping



BIT460

Figure 1: Concepts Implemented in Mapping

The mapping tasks are implemented by mapping programs referenced in Enterprise Services Repository.

Operation Mapping You use an operation mapping to relate an operation of an outbound service interface with an operation of an inbound service interface. Operation mapping is configured to reference mapping programs, which mediate between the different message types of two operations (from service interfaces), as illustrated in the following figure. Various mapping programs can be used as required to mediate between the output, input, and fault message types.

2011


3

BIT460




Figure 2: Mapping Programs Between Two Operations and Their Corresponding Message Types

In asynchronous cases, communication is based on just one message, so mapping is only required for the request. In synchronous cases, communication comprises a request, a response, and, where applicable, a fault message; you can therefore assign mapping programs in up to three different areas. The high-level process of developing an Operation Mapping is as follows: 1. 2. 3. 4.

Create an Operation Mapping in the Enterprise Services Builder. Assign sender and receiver Service Interfaces to the Operation Mapping. Select mapping programs for request (& response) message, save, and activate the object. Reference the Operation Mapping in an Interface Determination in the Integration Directory

Mapping-Program Types The figure Mapping Objects provides an overview of the mapping program types in Enterprise Services Repository, and the use of operation mappings in the Integration Directory.

4


2011




BIT460

Figure 3: Mapping Objects

Mapping programs used to map message types can be realized in the following different ways: •

Message mapping You create a Message Mapping graphically using the mapping editor in the Enterprise Services Builder.

•

Java mapping class You create a Java Mapping Class in a Java IDE, and import it into Enterprise Services Repository

•

XSL transformation You create an XSL transformation “externally” and import it into Enterprise Services Repository.

•

ABAP-XSL transformation You create an ABAP-XSL transformation on the Integration Server (in the ABAP stack) and reference it from within an operation mapping.

•

ABAP mapping class You create an ABAP mapping class on the Integration Server (in the ABAP stack) and reference it from within an operation mapping.

2011


5


BIT460


Combining Different Mapping Types Mapping programs can access other mapping programs and make use of their functions. This enables modularization and a reuse of existing developments. The only limitation is that the mapping programs must be in the same software component version or a basis software component version. See the following overview on mapping combinations: • • • •

Java classes in archives can be used in user-defined functions. Java classes can use the methods of other Java classes. XSLT mapping programs can insert or even import other XSLT mapping programs. Java methods can be called within XSLT mapping programs.

We recommend that you save Java classes and XSLT files in separate archives. Doing so can increase the rate of processing.

Multiple Mapping Programs in One Operation Mapping In an operation mapping, you have the option of using multiple mapping programs in succession and not just one, single program . However, when using multiple mapping programs in an operation mapping, note the following important restrictions: • • • • •

The first mapping program must have the appropriate source message. The output of each mapping program must match the input of the subsequent mapping program. The last mapping program must have the appropriate target message. Identical or different mapping types are possible. The sequence in which mapping programs are to be executed is specified. Hint: Not every mapping has to have the same source and target messages.

When you use the F4 help to select message mappings, you must not use any search criteria for the source and target messages. Otherwise only those message mappings that exactly match the expected source and target messages will be displayed.

6


2011


The mapping editor is of particular interest in this course. It is a graphical object editor that is used to create and test mapping programs before they are used in collaborative processes. Mapping programs developed with the mapping editor are called message mappings, although the other types of mapping programs do map messages as well.

BIT460


Using operation mapping in configuration You reference an operation mapping during configuration time in the Integration Directory. It can be referenced in the following configuration objects: For internal use by CSC only

in an Interface Determination


•

(for message processing by the Integration Engine) •

in an Enhanced Receiver Determination (for message processing by the Integration Engine)

•

in an Integrated Configuration (for message processing by the Advanced Adapter Engine) Hint: If you switch from one mapping program to another within an operation mapping, you do not need to make any changes in the configuration.

Enhanced receiver determination Enhanced receiver determination enables you to determine the receiver dynamically by using an operation mapping. In this case, an interface called ReceiverDetermination must be used as the receiver interface in the operation mapping. At runtime, the mapping is executed in the Receiver Determination step, independently of the mapping that later maps the sender interface to the receiver interface. Hint: The ReceiverDetermination service interface is in the Enterprise Services Builder in the SAP BASIS 7.30 software component (in the http://sap.com/xi/XI/System namespace).

2011


7

BIT460

Figure 4: Principle of Enhanced Receiver Determination

Hint: You cannot use the Enhanced Receiver Determination on the AEX (Advanced Adapter Engine Extended) because the AEX is configured with an Integrated Configuration, which does not support Enhanced Receiver Determination.

8


2011




BIT460


Exercise 1: Create an Operation Mapping Exercise Objectives For internal use by CSC only


After completing this exercise, you will be able to: • Check service interfaces and create operation mappings

Business Example Part of your daily responsibilities requires that you create and manage operation mappings.

Task 1: Check the Outbound Service Interface For the service interface CustomerInformation_Request in software component version (SWCV) SC_BIT_MAP, 1.0 in namespace http://educationsap.com/pi/mapping##: check which category the interface belongs to, which operations exist, and whether all the referenced objects exist. 1.

Check the attributes of the service interface

2.

Open the referenced objects and check the namespaces.

Task 2: Check the Inbound Service Interface Check the CustomerInformation_Provide service interface in software component version (SWCV) SC_BIT_BASE_COMP, 1.0 in the namespace urn:educationsap.com:bit:mapping to see whether all required objects exist. 1.

Check the attributes of the service interface.

2.

Open the referenced objects and check the namespaces.

Task 3: Create an Operation Mapping Create an operation mapping OM_CustomerInfoMap to map the service interfaces CustomerInformation_Request and CustomerInformation_Provide to each other. 1.

Create the operation mapping. Create the OM_CustomerInfoMap operation mapping for software component version SC_BIT_MAP 1.0 in your namespace http://educationsap.com/pi/mapping## to map the CustomerInformation_Request and CustomerInformation_Provide service interfaces to each other.

2011


9


BIT460

Solution 1: Create an Operation Mapping Task 1: Check the Outbound Service Interface For internal use by CSC only

1.

Check the attributes of the service interface a)

Display the service interface. Open software component version SC_BIT_MAP, 1.0, open the namespace http://educationsap.com/pi/mapping## and the node Service Interfaces. Then open the object CustomerInformation_Request by double-clicking.

b)

Check the interface category. On the Definition tab page, you can see that this is a service interface of category outbound.

c)

Confirm the interface operation mode. In section Operations, you see one operation named CustomerInformation_Request with mode synchronous. Note: A service interface of interface pattern “Stateless (XI30-Compatible)” can only have one operation, which name has to be the service interface name.

2.

Open the referenced objects and check the namespaces. a)

Check which message types are referenced. Check that the correct message types are referenced by checking the namespaces and also by navigating to the referenced message types and then to the data types by double-clicking.

b)

Check the namespace assigned to the data types. A message type has an XML Namespace field that can be used to enter a namespace for the data types used by the message types. Check this field in particular to see whether the namespace http://educationsap.com/pi/mapping## is also used here.

c)

Check message types exist. You can also start a check in the service interface by choosing Service Interface → Check (F7). If a message type has been entered that does not exist, an error message is displayed. Continued on next page

10


2011


For the service interface CustomerInformation_Request in software component version (SWCV) SC_BIT_MAP, 1.0 in namespace http://educationsap.com/pi/mapping##: check which category the interface belongs to, which operations exist, and whether all the referenced objects exist.

BIT460


Task 2: Check the Inbound Service Interface


1.

Check the attributes of the service interface. a)

Display the basis objects. You can either open the SWCV SC_BIT_BASE_COMP, 1.0, or navigate to the objects by expanding the node Basis Objects in the SWCV SC_BIT_MAP, 1.0.

b)

Display the selected objects. Choose Service Interfaces in the namespace urn:educationsap.com:bit:mapping and then open the object CustomerInformation_Provide by double-clicking.

c)

Check the operation category. On the Definition tab page, you can see that it has category inbound. The section Operations shows one synchronous operation.

2.

Open the referenced objects and check the namespaces. a)

Check which message types are referenced. Check that the correct message types are referenced by checking the namespaces and also by navigating to the referenced message types and then to the data types by double-clicking.

b)

Check the namespace assigned to the data types. There is an XML Namespace field that can be used to record a namespace for the data types used by the message types. Check this field in particular to see whether the namespace urn:educationsap.com:bit:mapping is also used here.

c)

Check message types exist. You can trigger a check in the service interface by choosing Service Interface → Check (F7). If a message type has been entered that does not exist, an error message is displayed.

Task 3: Create an Operation Mapping Create an operation mapping OM_CustomerInfoMap to map the service interfaces CustomerInformation_Request and CustomerInformation_Provide to each other. 1.

Create the operation mapping. Continued on next page

2011


11


Check the CustomerInformation_Provide service interface in software component version (SWCV) SC_BIT_BASE_COMP, 1.0 in the namespace urn:educationsap.com:bit:mapping to see whether all required objects exist.


BIT460


a)

Create a new operation mapping. 1.

2. 3. 4. b)

Display the objects for your namespace http://educationsap.com/pi/mapping##. To create a new operation mapping, choose New in the context menu. In the Create Object dialog box, expand the section Mapping Objects on the left-hand, and choose Operation Mapping Enter the name OM_CustomerInfoMap and choose Create. Save the new operation mapping.

Specify the outbound and inbound interfaces. 1.

Enter the outbound interface CustomerInformation_Request and the inbound interface CustomerInformation_Provide by using the input help. Alternatively, you can drag the interfaces to the relevant fields by using drag and drop. Caution: When using drag and drop, remember to enter a value in the fields for Namespace and Software Component Version.

2.

To display detailed information at the bottom of the screen, in particular the three tab pages Request, Response, and Fault, choose Read Operations. Caution: Ensure that the tab Fault is listed. If the Fault tab is not listed, this may lead to errors later, even though no fault message is defined in our interfaces. Choose Read Operations to list tabs.

c)

Save the operation mapping. Note: It is not yet possible to activate the operation mapping.

d)

Display the available mapping programs. You can see which types of mapping programs can be used here, by using the input help for the Type field (located under Mapping Programs for request): • •

Message Mapping Java Class Continued on next page

12


2011


Create the OM_CustomerInfoMap operation mapping for software component version SC_BIT_MAP 1.0 in your namespace http://educationsap.com/pi/mapping## to map the CustomerInformation_Request and CustomerInformation_Provide service interfaces to each other.

BIT460


XSL ABAP Class ABAP XSL Hint: The operation mapping is just created to enable you to see the selection process. You create the message mapping at a later stage and reference it in the operation mapping. When you have done all this, you can activate the operation mapping.

2011


13



• • •


BIT460

Lesson Summary


14



You should now be able to: • Create an Operation Mapping • Check the inbound and outbound service interfaces • List the available mapping program types for PI

2011

BIT460

Unit Summary

Unit Summary


2011



You should now be able to: • Create an Operation Mapping • Check the inbound and outbound service interfaces • List the available mapping program types for PI

15

Unit Summary

BIT460



16


2011






Mapping Messages Unit Overview Introduction to message mapping.

Unit Objectives After completing this unit, you will be able to: • • • • • • •

Create a message mapping Use the mapping editor and explain how it works Test a message mapping Use trace information to help debug issues that arise during the testing process Create and test a configuration scenario Implement standard functions in your own message mappings Create and implement user-defined functions in message mappings

Unit Contents Lesson: Creating a Message Mapping........................................ 18 Exercise 2: Create a Message Mapping ................................. 27 Lesson: Testing a Message Mapping ......................................... 32 Exercise 3: Test a Message Mapping..................................... 39 Exercise 4: Create the Configuration ..................................... 41 Lesson: Using Message-Mapping Functions................................. 50 Exercise 5: Use Standard Message-Mapping Functions............... 57

2011


17


Unit 2

Unit 2: Mapping Messages

BIT460

Lesson: Creating a Message Mapping Lesson Overview For internal use by CSC only

Lesson Objectives After completing this lesson, you will be able to: • •

Create a message mapping Use the mapping editor and explain how it works

Business Example You are responsible for the development of mappings in SAP NetWeaver Process Integration and must be able to create, modify, and manage mappings that are developed. For this reason, you need to know: • • •

How the mapping editor works How to modify the message-mapping structure How to make use of variables and advanced functions in the mapping editor

The Mapping Editor The Enterprise Services Builder has an integrated mapping editor that you can use to graphically represent and manage mappings. Since this involves mappings between messages, we refer to this procedure as message mapping. In Enterprise Services Repository, Java programs are generated from message mappings. These Java programs are compiled for the runtime and packed into JAR files. The process occurs automatically and does not have to be triggered by the user, or monitored in any way. Graphical mapping tools provide an easy-to-use method of defining connections between source and target structures and values, in addition to the integrated functions that you can use. To help overcome problems when dealing with complex messages you can add your own user-defined functions to the existing standard functions.

18


2011


This lesson introduces the basic concepts of the mapping editor and shows you how to use the mapping editor to create a message mapping.

BIT460

Lesson: Creating a Message Mapping


•

Java Programs generated from message mappings: – Enhanced with integrated standard functions

• •

– Enhanced with user-defined Java functions Java programs imported as JAR or Zip archives XSLT files imported as JAR or Zip archives: – Enhanced with integrated standard functions

•

– Enhanced with user-defined Java functions ABAP classes and XSLT programmed on the PI ABAP stack

As an alternative to the mapping programs generated by the mapping editor, you can specify Java programs or XSLT files as imported archives directly in the operation mapping as mapping programs. If required, you can also use the integrated and user-defined functions (listed above) in XSLT files. ABAP mappings are developed in the ABAP Workbench and are not imported into Enterprise Services Repository since during runtime, these mapping programs are executed directly in the ABAP Workbench of the PI ABAP Stack.

The Message-Mapping Structure All mappings are based on the principle that the fields of a target structure are assigned to fields in a source structure; a field can be either an element or an attribute from the relevant XML document. An assignment can comprise a complex combination of functions, which are needed, for example, for calculations or format conversions. To ensure order and clarity, you can split the mapping into sub mappings for each assignment; each sub mapping is displayed in the mapping editor in a separate area. The figure Structure Overview and the Data-Flow Editor illustrates the two overviews provided by the mapping editor: •

Structure: The structure overview displays the structures of the selected source and target documents. You can extend the structure overview to include a representation of assignments between elements in the documents.

•

Data-flow: The data flow editor displays the sub mapping for the target field selected in the structure overview.

2011


19


Graphical mapping is one method of defining a mapping in PI. However, there are others. Users with the appropriate knowledge and experience with mapping can sometimes find it helpful to use an alternative mapping type, such as: Java, ABAP, or XSLT mapping. These alternative mapping programs are summarized in the following list:

BIT460




Figure 5: Structure Overview and the Data-Flow Editor

Source and Target Structures Various methods are available for generating the source and target structures that are imported into the mapping editor. For example, you can use any message types generated in Enterprise Services Repository, where the underlying structure of the message type is stored in XSD. The mapping editor also supports the use of imported external definitions; the import process automatically extracts the structure of XML files. As a general rule, any XSD files created with the data type editor can be imported. However, some tags from XSD files are ignored. For example, the tags and are not supported. The mapping editor supports the import of the following message-type structures, files, and definitions: •

From Enterprise Services Repository: – Message types developed in Enterprise Services Repository – Imported external definitions (WSDL, XSD, or DTD files)

•

– Imported SAP metadata (RFC or IDoc) From the local file system (XSD or XML files): – Not all XSD tags are supported (all XSD tags generated using the data type editor can be imported) – and are not supported

20


2011

BIT460


Data Flow Configuration


•

Field-assignment Method 1: Transfer the target field to the data flow editor by double-clicking or by using drag and drop. Source fields can be transferred in the data flow editor in the same way. If a mapping already exists for the selected target field, this is shown in the data flow editor, and allows you, for example, to create additional mappings for further source fields. You assign fields by simply drawing lines between the source and target fields.

•

Field-assignment Method 2: Connect the target and source elements using drag and drop. This automatically creates the assignment link between the fields.

Figure Connecting Source and Target Fields illustrates the field-assignment methods outlined above.

Figure 6: Connecting Source and Target Fields

Hint: PI also allows you to define target-field mappings for multiple target fields simultaneously.

2011


21


The mapping editor includes a data flow editor, which you can use to map fields in the source message structure to the appropriate fields in the target message structure. You can use the following methods for assigning target fields to the corresponding source fields:


BIT460


Figure 7: Data-Flow Editor: Target-Field Mapping for Multiple Target Fields Simultaneously

Message-Mapping Field Variables PI enables the use of variables in the target structure. Before defining target-field mappings, you can use variables to calculate a value that can be reused in several target-field mappings for one block. If several target fields have identical mappings, less time is required to define them; you define the target-field mapping once for one variable and then assign this variable to all other target fields. In the following example, a date must be formulated comprising a month, day, and year. This date then has to be mapped to the Date and TimeStamp target fields. The variable DateVar simplifies these two target-field mappings:

22


2011


The data flow editor can contain multiple target fields with identical (or at least similar) target-field mappings. This feature not only simplifies the mapping procedure, it also enables you to execute complex functions once and assign the resulting value to multiple target fields. For performance reasons, we highly recommend that you use this feature.




BIT460

Figure 8: How Graphical Variables Are Used (Example)

Hint: To create a variable, use the context menu for a field in the target structure that possesses additional subelements and choose Add Variable. The mapping editor inserts the variable as the first subnode of the field. This variable is visible for all nodes at the same hierarchy level and all subnodes. You can use the Var variable as a target field, too, or define a target-field mapping for Var in the data flow editor. In the target-field mapping, you can also use values from variables that appear before Var in the structure flow. To use a variable as a source field in a target-field mapping, drag the variable to the data flow editor.

Advanced Message-Mapping Functions The application toolbar in the mapping editor displays icons you can use to start functions that make it easier to create mappings. The following table lists and explains some of the more commonly used functions.

2011


23


24

Function

Description

Preview the mapping in pure text format.

Preview the target-field mapping in pure text format in the data flow editor.

Activate the mass-assignment option.

Before you start a mass assignment operation, you must select both nodes in the source and target structures. Mass assignment ensures that any fields with the same names that are located under the selected nodes are automatically connected. The few remaining target fields that remain unlinked must be mapped manually. The mass-assignment function is particularly useful if you need to map larger structures, such as IDoc data.

Display a graphical view that outlines dependencies between source and target fields.

You can use this function for specific target fields, for sub structures, or for the whole structure, and can simply close it when it is no longer required.


2011



Icon

BIT460




BIT460

Figure 9: GUI Message-Mapping Functions

2011


25


BIT460



26


2011

BIT460


Exercise 2: Create a Message Mapping Exercise Objectives For internal use by CSC only

Business Example You are responsible for mapping one message structure (type) to another. For this reason, you want to create a message mapping and use it in an operation mapping.

Task 1: Create a message mapping to map message types MtCustomerName and MtName. 1.

Create the new message mapping MM_CustomerNameMerge. In software component version SC_BIT_MAP, 1.0, in your namespace http://educationsap.com/pi/mapping##, create the message mapping MM_CustomerNameMerge to map the message types MtCustomerName (SWCV SC_BIT_MAP, 1.0, namespace http://educationsap.com/pi/mapping##) and MtName (SWCV SC_BIT_BASE_COMP, 1.0, namespace urn:educationsap.com:bit:mapping) to one another. Map the two fields Surname and Name from the source structure so that they are separated by a blank in MtName. The sequence must be: first name, then surname.

Task 2: Reference the message mapping in the operation mapping OM_CustomerInfoMap. 1.

2011

Reference the message mapping MM_CustomerNameMerge in the operation mapping OM_CustomerInfoMap.


27


After completing this exercise, you will be able to: • Create message mappings in Enterprise Services Repository • Reference message mappings in operation mappings


BIT460

Solution 2: Create a Message Mapping Task 1: For internal use by CSC only

1.

Create the new message mapping MM_CustomerNameMerge. In software component version SC_BIT_MAP, 1.0, in your namespace http://educationsap.com/pi/mapping##, create the message mapping MM_CustomerNameMerge to map the message types MtCustomerName (SWCV SC_BIT_MAP, 1.0, namespace http://educationsap.com/pi/mapping##) and MtName (SWCV SC_BIT_BASE_COMP, 1.0, namespace urn:educationsap.com:bit:mapping) to one another. Map the two fields Surname and Name from the source structure so that they are separated by a blank in MtName. The sequence must be: first name, then surname. a)

Create a new message mapping. 1. 2. 3.

b)

In SWCV SC_BIT_MAP, 1.0 navigate to your namespace http://educationsap.com/pi/mapping##. To create a new message mapping, choose New in the context menu. Enter the name MM_CustomerNameMerge and choose Create.

Select the source message type. 1.

2. 3.

In the tree structure in your namespace http://educationsap.com/pi/mapping## (software component SC_BIT_MAP), navigate to the Message Types node. Locate the message type MtCustomerName. Drag the message type MtCustomerName to the section Enter a source message (above the structure section) in the source message structure. Hint: Only the name of the message type is listed in the graphical mapping editor display (for example, MtCustomerName), and not the name of the referenced data type (for example, PersonName).

Continued on next page

28


2011


Create a message mapping to map message types MtCustomerName and MtName.

BIT460


c)

Select the target message type.

2. 3. d)

Display mapped fields in the data flow editor. 1. 2. 3.

4.

5. e)

Double-click the target field MtName and the source fields Surname and Name to display them in the data-flow editor. Select the Text function and drag the concat function to the data-flow editor. Drag one connection line from the Name outbound field (on the right-hand side) to the concat inbound field on the upper left-hand side (since the first name should come first). Drag another connection line from the Surname outbound field (on the right-hand side) to the concat inbound field on the lower left-hand side. Drag a connection line from the concat outbound field to the MtName inbound field.

Separate mapped fields with a delimiter. 1. 2.

f)

In the tree structure in your namespace urn:educationsap.com:bit:mapping (software component SC_BIT_BASE_COMP), navigate to the Message Types node. Locate the message type MtName. Drag the message type MtName to the Enter a target message section in the target message structure.

Double-click the concat function and enter a blank as a delimiter to separate the Name and Surname fields with a blank. Choose OK to exit the screen for maintaining the properties of the concat step.

Display the mapping as text. To display the mapping as text, choose Text Preview. /ns1:MtName=concat(/ns0:MtCustomerName/Name, /ns0:MtCustomerName/Surname, delimeter= )

g)

Save and activate the message mapping.


2011


29



1.


BIT460

Task 2: Reference the message mapping in the operation mapping OM_CustomerInfoMap. For internal use by CSC only

Reference the message mapping MM_CustomerNameMerge in the operation mapping OM_CustomerInfoMap. a)

Display the operation mapping. In your namespace http://educationsap.com/pi/mapping##, navigate to the Operation Mappings node and open the operation mapping OM_CustomerInfoMap by double-clicking it.

b)

Maintain the message mapping. Switch to change mode and use the input help on tab Request in the section below Mapping Program to select your message mapping MM_CustomerNameMerge.

c)

30

Save and activate the operation mapping.


2011


1.

BIT460


Lesson Summary


2011



You should now be able to: • Create a message mapping • Use the mapping editor and explain how it works

31


BIT460

Lesson: Testing a Message Mapping For internal use by CSC only

This unit explains how message mappings function and what options you have for testing. You will also learn how to create and test a configuration.


Test a message mapping Use trace information to help debug issues that arise during the testing process Create and test a configuration scenario

Business Example You are responsible for the development of mappings in SAP NetWeaver Process Integration and need to know how message mappings function. You also need an overview of the tools the mapping editor provides to enable you to test message mappings.

Testing Procedures in Message Mapping Enterprise Services Repository generates Java programs out of message mappings, which are compiled for the runtime and packed into JAR files. If you create a message mapping and save it without producing errors, this merely indicates that it can be compiled. It means that you have set all target fields that you are required to set, and that there are no unset arguments for the functions used. Note that, despite the apparent completeness or accuracy of your data, you may still encounter difficulties at runtime.

32


2011


Lesson Overview

BIT460

Lesson: Testing a Message Mapping

To help you understand the reasons for unexpected mapping results or why exceptions occur at runtime, note the following points, which explain how message mappings are processed at runtime: For internal use by CSC only

Source Fields: Source fields are read into queues by the message mappings. This procedure improves performance and enables large messages to be processed, since the entire message does not actually have to be stored in the memory as a tree structure.

2.

Queues: Queues are processed by the functions of the target-field mappings. Additional functions can be allocated to the result queues if multiple functions are called in succession.

3.

Target Fields: Values from the result queues are used to fill the target fields. As part of the process, the values are compared to the attributes for occurrence (the number of times a field appears in one or more hierarchy structures) in the following way: •

Upper Occurrence Limit: If the upper limit for the number of occurrences of a target field is exceeded, additional result values from the result queue are ignored.

•

Lower Occurrence Limit: If the lower limit for the number of occurrences of a field is not reached, an exception is triggered.

2011


33


1.

BIT460




Figure 10: Processing Message Mappings

Message-Mapping Queues A message-mapping queue consists of all the values of a field in the data flow editor. This applies to source fields, target fields, and any fields created by mapping steps. These queues serve as important tools for testing since you can display them in the message mapping as soon as test data is available. This applies not only to source fields, but to every processing step in the message mapping process. The message-mapping process makes use of the following queues: •

Inbound queue Data from fields in the source message

•

Processing queue Data from inbound queues, which is being processed by the message-mapping template

•

Result queue Data for entry in fields in the target message Hint: You can debug the individual steps in the message-mapping process by displaying the queue for each function in the message mapping. This is explained in more detail in the Queues and Context lesson.

34


2011

BIT460


Trace Messages


You can assign trace messages any trace level, regardless of their level of importance (priority). The following trace levels are possible: • • •

1 (Information) 2 (Warning) 3 (Debug)

Pipeline processing is also specified a trace level. You can only see a trace message in the monitor if its priority has at least the same trace level as the pipeline processing. If the trace level of the pipeline, for example, is level 1, debug messages, which are level 3, are not displayed. Hint: You specify the trace level of the pipeline in the configuration for the Integration Engine. Call transaction SXMB_ADM, choose Integration Engine Configuration and, under Specific Configuration Data, choose RUNTIME as the category and TRACE_LEVEL as the parameter.

Test Environment for Operation Mapping After you have defined an operation mapping, you can check whether it functions correctly at runtime by using the Test tab page in the mapping editor. You can test the mapping for either the request, response, or fault message. Caution: Make sure that the mapping programs to be tested are in Enterprise Services Repository. You cannot test ABAP mappings. Note that, for the generated Java source code to compile, message mappings must be complete.

Test Environment for Message Mapping The Test tab in the Mapping Editor structure overview provides functions that you can use to test the accuracy of your mappings. The functions are displayed in the application toolbar at the top of the Test tab page. The various icons and their functions are illustrated in the figure below.

2011


35


During runtime testing, it is possible to write information about the current status of the message-mapping process to a trace file. You can view the tracing data in the trace area for the message in the message monitor (SOAP Header → Trace). However, you can only view the trace data the earliest after the message mapping successfully completes, that is, after the processing step Request Message Mapping. You can also view the trace data when testing message mappings in Enterprise Services Repository, assuming the trace level there is set accordingly.

BIT460

Figure 11: GUI Standard Functions in Test

After you load an XML file or create an empty XML structure, you can set the values and attributes in either the graphical editor or the text-based editor. In the graphical editor, you can use the options in the context menu to duplicate subtrees, delete nodes, and add elements or attributes. In the text-based editor, you have to perform each of the add, delete, and duplicate steps manually. However, the text-based editor enables you to create test cases for PI scenarios quickly and easily by using the copy-and-paste feature. You can also use header parameters when testing. Header parameters are not business fields in the payload; header parameters are meta information such as the sender interface - parameters that are available as runtime constants in the PI-SOAP message header at runtime. When you start the mapping process for testing purposes, you can observe the test results in the structure overview for the target fields.

Mapping Testing Functions The mapping test environment provides the following functions, which are available on the Test tab page in the structure overview.

36


2011




BIT460


Icon

Test Function Load an XML file from the local file system to define the source values.


Start the message-mapping process. Create and open a test case Save a test case Delete a test case Switch to the graphical message-mapping editor (toggle display details ) Switch to the text-based message-mapping editor

2011


37


Create an empty source structure; you then manually enter data for this structure.


BIT460



38


2011

BIT460


Exercise 3: Test a Message Mapping Exercise Objectives For internal use by CSC only

Business Example You want to check whether a message mapping you created functions correctly, without having to apply it at runtime.

Task: Test your message mapping MM_CustomerNameMerge.

2011

1.

Open your message mapping MM_CustomerNameMerge.

2.

Maintain your test data and perform a test.

3.

Create a test case.


39


After completing this exercise, you will be able to: • Test message mappings in Enterprise Services Repository


BIT460

Solution 3: Test a Message Mapping Task: For internal use by CSC only

1.

Open your message mapping MM_CustomerNameMerge. a)

2.

3.

40

In SWCV SC_BIT_MAP, 1.0, navigate to your namespace http://educationsap.com/pi/mapping##, choose the Message Mappings node, and open your message mapping by double-clicking it.

Maintain your test data and perform a test. a)

Navigate to the test interface by choosing the Test tab page (beside Definition).

b)

Enter values for the Surname and Name fields.

c)

Execute the test by choosing the Start Transformation icon at the bottom of the screen on the left.

d)

Messages are displayed in the lower area. If a test if successful, the results are displayed in the right-hand area of the window.

Create a test case. a)

Switch to edit mode for the message mapping.

b)

Create a test case by choosing the Add Test Instance icon (top row, third icon from the left). Name the test case TEST1_##.

c)

Delete the entered values by choosing Create Instance (second icon from left). Open your test case by choosing Open Test Case / TEST1_## (sixth icon from left). Your saved values are now entered.


2011


Test your message mapping MM_CustomerNameMerge.

BIT460


Exercise 4: Create the Configuration Exercise Objectives For internal use by CSC only

Business Example You want to test your mapping at runtime using a configured scenario.

Task: Configure a scenario between the sender BC_CI_Requestor_## and the receiver Training with the interfaces CustomerInformation_Request and CustomerInformation_Provide using your operation mapping OM_CustomerInfoMap. 1.

Create a new configuration scenario CS_BIT_CustomerInfo_##.

2.

Create a new business component BC_CI_Requestor_## and add it to your configuration scenario CS_BIT_CustomerInfo_##.

3.

Maintain the sender interface for the Business Component. Maintain the sender interface CustomerInformation_Request from your namespace http://educationsap.com/pi/mapping## for your business component BC_CI_Requestor_##.

4.

Create a communication channel BC_CI_Req_##_HTTP_Sender for sender BC_CI_Requestor_##. Adapter Type shall be HTTP, Sender.

5.

Create a sender agreement for sender BC_CI_Requestor_##, interface CustomerInformation_Request and channel BC_CI_Req_##_HTTP_Sender.

6.

Create a receiver determination for sender BC_CI_Requestor_## and the sender interface CustomerInformation_Request from the namespace http://educationsap.com/pi/mapping## and maintain the business system Training as the receiver.

7.

Create an interface determination for this receiver determination. Specify CustomerInformation_Provide as the receiver interface in the namespace urn:educationsap.com:bit:mapping. Reference your operation mapping OM_CustomerInfoMap as the mapping.

8.

Create a receiver agreement for the parameters mentioned above, by referencing the existing communication channel Training_Proxy_In. Continued on next page

2011


41


After completing this exercise, you will be able to: • Create the required configuration for testing purposes


9.

BIT460

Save and activate all objects.

10. Test the changes.


42


2011


Start the HTTP client and send a suitable request. Test the result in the HTTP client and in the message monitor of the Integration Server.

BIT460


Solution 4: Create the Configuration Task: For internal use by CSC only

1.

Create a new configuration scenario CS_BIT_CustomerInfo_##. a)

Log on to the Integration Directory.

b)

Create a configuration scenario. 1. 2. 3.

4. c) 2.

Navigate to Object → New → Administration and choose Configuration Scenario. Name the scenario CS_BIT_CustomerInfo_##. Enter a description for the configuration scenario (for example, “Mapping Test”), and select No Model under Type of ES Repository Model. Create the configuration scenario: choose Create.

Save your configuration scenario.

Create a new business component BC_CI_Requestor_## and add it to your configuration scenario CS_BIT_CustomerInfo_##. a)

Create the business component. Navigate to Object → New → Collaboration Profile and choose Business Component.

b)

Define the business-component properties. Leave the Party field empty, name your business component BC_CI_Requestor_##, enter Sender as the description, and select your scenario CS_BIT_CustomerInfo_## in the Add to Scenario field.

3.

c)

Create your business component; choose Create.

d)

Save your business component.

Maintain the sender interface for the Business Component.


2011


43


Configure a scenario between the sender BC_CI_Requestor_## and the receiver Training with the interfaces CustomerInformation_Request and CustomerInformation_Provide using your operation mapping OM_CustomerInfoMap.


BIT460

Maintain the sender interface CustomerInformation_Request from your namespace http://educationsap.com/pi/mapping## for your business component BC_CI_Requestor_##. For internal use by CSC only

Edit the sender interface. On the detail screen for your business component BC_CI_Requestor_## (in edit mode), navigate to the Sender tab page.

b)

Select and assign the service interface. To reference your service interface CustomerInformation_Request from your namespace http://educationsap.com/pi/mapping## of software component version SC_BIT_MAP (1.0), use the input help for the Name field (located under Outbound Interfaces).

c)

Save the business component. Hint: When you assign an interface to the business component, the assigned interface appears in the input help in the configuration that follows.

4.

Create a communication channel BC_CI_Req_##_HTTP_Sender for sender BC_CI_Requestor_##. Adapter Type shall be HTTP, Sender. a)

Create object: communication channel Navigate to Object → New → Collaboration Profile and choose Communication Channel.

b)

Maintain Communication Component and Communication Channel name. Select Communication Component BC_CI_Requestor_## and enter the name for the new Communication Channel as BC_CI_Req_##_HTTP_Sender. Choose Create to create the object.

c)

Select Adapter Type HTTP. Keep all other parameters to their default value. Save the channel.


44


2011


a)

BIT460


5.

Create a sender agreement for sender BC_CI_Requestor_##, interface CustomerInformation_Request and channel BC_CI_Req_##_HTTP_Sender. a)

Create a new sender agreement.


b)

Specify the sender agreement properties. Leave the Communication Party field empty, and enter BC_CI_Requestor_## as the sender and CustomerInformation_Request as the interface. If you use the input help for all fields, the namespace http://educationsap.com/pi/mapping## is entered automatically.

c)

Create the sender agreement: choose Create.

d)

Select the communication channel. Use the input help for Sender Communication Channel to select the channel BC_CI_Req_##_HTTP_Sender.

e) 6.

Save the sender agreement.

Create a receiver determination for sender BC_CI_Requestor_## and the sender interface CustomerInformation_Request from the namespace http://educationsap.com/pi/mapping## and maintain the business system Training as the receiver. a)

Create a new receiver determination. Navigate to Object → New → Configuration Objects and choose Receiver Determination.

b)

Specify the receiver-determination properties. Leave the Communication Party field empty, and enter BC_CI_Requestor_## as the sender of your business component and CustomerInformation_Request as the interface. If you use the input help for all fields, the namespace http://educationsap.com/pi/mapping## is entered automatically.

c)

Create the receiver determination: choose Create.

d)

Maintain the business system. Under Configured Receivers, maintain business system Training as the receiver in the Communication Component field using the input help.

e) 7.

Save the changes to your receiver determination.

Create an interface determination for this receiver determination.


2011


45


Navigate to Object → New → Collaboration Agreements and choose Sender Agreement.


BIT460

Specify CustomerInformation_Provide as the receiver interface in the namespace urn:educationsap.com:bit:mapping. Reference your operation mapping OM_CustomerInfoMap as the mapping. For internal use by CSC only

Display the receiver determination configuration. 1.

2. b)

In your receiver determination, choose the Configuration Overview tab page. Navigate to the lower area Configuration Overview for Receiver Determination. Use the small triangular icon to the left of Training (and under Receiver) to expand the display.

Select the receiver determination. Select the entry CustomerInformation_Request. A list of existing configuration objects now appears in the Objects of Selected Connection area on the right of the screen. The Receiver Determination line should contain only one entry.

c)

Specify a new interface determination. In the Objects of Selected Connection area, click the interface determination line and create a new interface determination by choosing New Specific from the context menu. You have now predefined all the known parameters in the interface determination.

d)

Specify the receiver interface. Use the input help for the field Operation Mapping to select your operation mapping OM_CustomerInfoMap (SC_BIT_MAP 1.0). Hint: The receiver interface CustomerInformation_Provide (namespace urn:educationsap.com:bit:mapping) is derived from the operation mapping.

e)

Reference the operation mapping. To use the input help for the operation mapping, navigate to the Operation Mapping field. Reference your operation mapping OM_CustomerInfoMap in the namespace http://educationsap.com/pi/mapping## (SWCV SC_BIT_MAP 1.0).

f)

Save your interface determination. Close the interface determination to return to the configuration overview for the receiver determination.

g)

Display the newly referenced interface determination.


46


2011


a)

BIT460


Refresh the display under Configuration Overview for Receiver Determination by using the Refresh icon. Your interface determination is now listed in the Objects of Selected Connection area. For internal use by CSC only

Create a receiver agreement for the parameters mentioned above, by referencing the existing communication channel Training_Proxy_In. a)

Create a receiver agreement. In the Objects of Selected Connection area, click the receiver agreement line and create a new receiver agreement by choosing New Specific from the context menu. You have now predefined all the known parameters in the receiver agreement.

b)

Reference the existing communication channel. Use the input help to reference the existing communication channel Training_Proxy_In in the Receiver Communication Channel field of the receiver agreement.

c)

Save your receiver agreement. Close the receiver agreement to return to the configuration overview for the receiver determination.

d)

Display the newly added receiver agreement. Refresh the display under Configuration Overview for Receiver Determination by using the Refresh icon. Your receiver agreement is now listed with the name of the communication channel directly below it.

9.

Save and activate all objects. a)

Display the changed lists. Switch to the Change Lists tab page in the Integration Builder.

b)

Activate all changes. Choose Activate from the context menu of the Standard Change List node.

c)

In the displayed list, leave all objects selected and choose Activate.

10. Test the changes.


2011


47


8.


BIT460

Start the HTTP client and send a suitable request. Test the result in the HTTP client and in the message monitor of the Integration Server. a)

Open the HTTP client.


b)

Start the HTTP client. This simulates an application that generates an XML document and then sends it to the SAP PI pipeline by using the HTTP adapter. If necessary, correct the details for the sender service so that they match those for your scenario configuration.

c)

Transfer the document to the pipeline; choose Send. Since this involves synchronous communication (quality of service is BE for “Best Effort”), a response appears in the form under Result in the last text area.

d)

Check the status of the test message. Call transaction SXI_MONITOR on the Integration Server and check the processing of your messages in the message monitor.

e)

Display trace information. Navigate to the detail view of your message and open the trace (under SOAP Header → Trace) in the processing step Request Message Mapping in either one of the windows.

f)

Locate the trace messages relating to message-mapping and operation mapping. At the bottom of the trace area, you can find the message indicating which operation mapping and mapping program were executed: Operation Mapping http://educationsap.com/pi/mapping## OM_CustomerInfoMap Mode 0 ... Call method execute of the application Java mapping com.sap.xi.tf._MM_CustomerNameMerge_ Java mapping com/sap/xi/tf/_MM_CustomerNameMerge_ completed. executeStep() of com.sap.xi.tf._MM_CustomerNameMerge_

48


2011


Open the HTTP client from the file share. Your instructor will tell you where to find the file.

BIT460


Lesson Summary


2011



You should now be able to: • Test a message mapping • Use trace information to help debug issues that arise during the testing process • Create and test a configuration scenario

49


BIT460

Lesson: Using Message-Mapping Functions For internal use by CSC only

This lesson explains how to use standard functions in message mapping and provides examples of how some of the more common functions can be implemented. You will also learn how to create and make use of user-defined functions in message mapping.


Implement standard functions in your own message mappings Create and implement user-defined functions in message mappings

Business Example You are responsible for the development of mappings in SAP NetWeaver Process Integration and require an overview of the purpose and use of standard functions for message mapping in the mapping editor. You also need to understand how to create user-defined functions in message mapping.

Predefined Message-Mapping Functions A simple assignment between source fields and target fields is not always sufficient to produce the required level of accuracy and efficiency in the message-mapping process. The mapping editor provides a variety of standard functions for use in the mapping of message structures. The predefined functions are organized into different categories, for example: text strings, arithmetic calculations, (runtime) constants, conversions, date format conversions, boolean comparisons, statistical functions for all fields of a context, and functions for special structure mappings. Hint: If you double-click anywhere in the background of the data flow editor, the system displays a menu containing all the standard functions that you can select, as well as a separate list containing the functions you used last. You can also copy the paths of functions in the data flow editor and use them for other target fields. The figure Generic Standard Functions illustrates some generic examples of standard functions. This lesson also provides further examples of the common usages for text, date, boolean, and arithmetic functions in message mapping.

50


2011


Lesson Overview

Lesson: Using Message-Mapping Functions

Figure 12: Generic Standard Functions

Note: Input values and returned output values are mandatory for all functions except generating functions. For example, a constant function does not require input values. For some functions, you must set parameters. For example, the separator property in the concat function must be defined. You can enter values for parameters by double-clicking the function used in the data-flow editor. A function handles all source and target fields as strings. For none string input parameters (for example, integers), the contents of that parameter undergo a data-type conversion (casting). If the values cannot be converted successfully, the mapping runtime triggers a Java exception.

Text Functions in Message Mapping The following figure outlines the standard text function concat and illustrates how it works.

Figure 13: concat Standard Function

2011


51



BIT460


BIT460

The following figure illustrates how to use the standard text function substring. Note that parameters must be set for this function.


Figure 14: substring Standard Function

Date Functions in Message Mapping The following figure illustrates how to use the standard date function dateTrans. Note that parameters must be set for this function.

Figure 15: dateTrans Standard Function

52


2011


Hint: For the substring function, the parameters that need to be maintained are not the parameters that are displayed, and that the index count starts at 0.

BIT460


The dateTrans function has some enhanced settings. For example, in addition to date formats, the numbering for weekdays and calendar weeks is country-specific. You define the necessary conventions for this in the function properties. For internal use by CSC only

First Weekday This parameter defines which day of the week is the first day of the week. For example, in the USA it is Sunday, but in France it is Monday. The numbering starts at 1.

•

Minimum Number of Days Required in the First Week This parameter defines how many days the first week of a year must have for it to be counted as the first calendar week.

•

Calendar Is Lenient This checkbox enables you to control whether invalid dates trigger an exception or not.

Boolean Functions in Message Mapping Boolean message-mapping functions evaluate conditions that return Boolean values. Standard functions that return Boolean values return the string true or false. Standard functions that expect Boolean values interpret the values “1” and “true” (not case-sensitive) as true and all other values as false. The Boolean functions If and IfWithoutElse are illustrated in the figure Boolean Functions. Boolean functions return the values true or false. The values 1 or true (not case-sensitive) can be used as input values for true.

Figure 16: Boolean Functions

2011


53


•


BIT460

Arithmetic Functions in Message Mapping


The figure Arithmetic Functions: FormatNum explains FormatNum, the most important arithmetic function, and how it works. The results returned by arithmetic operations can be converted to the required target format by using FormatNum.

Figure 17: FormatNumber arithmetic function

User-Defined Functions in Message Mapping If the standard functions for a target-field mapping do not fulfill your requirements, or if the graphical representation becomes unclear due to the complexity of the message-mapping structure, you can create your own user-defined functions. You can create Java source text in this function, and the ES Builder saves it in a local function library for use in the message-mapping process. Hint:

54


2011


You can only enter numerical values for the arithmetic function category (this includes values with digits after the decimal point). If the value cannot be interpreted as a digit, then the system triggers a Java exception. Otherwise, all calculations are executed with the precision of the Java data type float. The format of the result value depends on the result: If the result is a value with digits after the decimal point, these remain unchanged. In results, any trailing zeros after the decimal point are deleted to enable conversion back into string format. For example, the result of the calculation 4.2 - 0.2 is 4 and not 4.0.

BIT460


To use a user-defined function in more than one message mapping or mapping template, create the user-defined functions in function libraries in the ES Repository. For internal use by CSC only

Caution: It is important to test any new user-defined function in the test environment before releasing it for use in a wider implementation.

Message-Mapping Function Categories The mapping editor provides a selection of standard functions to help define message mappings. The functions are organized in the categories listed and described in the following table:

2011

Function Category

Action

Arithmetic functions:

Calculate or format values in message-mapping fields, for example: add, subtract, greater, or FormatNum

Boolean functions:

Implement conditions in your mappings, for example: If and IfWithoutElse. All functions in this category expect Boolean input values.

Constant functions:

Generate a value for a target field rather than take the value from a source field, for example: Constant and CopyValue.

Conversion functions:

Execute a value mapping using a fixed or assigned value table, for example: FixValues and Valuemapping.

Date functions:

Define the date format for the source or target message-mapping structure, for example: dateTrans (convert date format) and CompareDate. The format adheres to the convention as defined in the standard Java class java.util.SimpleDateFormat.


55


The user-defined function is included in the Java coding that is generated for the message mapping as a Java method. The new (user-defined) function is visible in the data flow editor in the function category that you assigned to the function in the function properties. You can insert user-defined functions in the data flow editor in the same way as you insert a standard message-mapping function.

56

BIT460

Function Category

Action

Node functions:

Manipulate structure and context in your mappings, for example: createIf (insert structuring elements) and removeContexts (remove all higher-level contexts of a source field).

Statistical functions:

Designed for source fields that occur more than once in the message-mapping source structure (maxOccurs = i > 1), for example: sum (sum of values in a context), average (average of values in a context), and count (number of fields in a context).

Text functions:

Return or compare text strings in a message-mapping structure, for example: substring (return text string “A” for “B”), concat (merge text strings), and compare (compare text strings).


2011




BIT460


Exercise 5: Use Standard MessageMapping Functions For internal use by CSC only

After completing this exercise, you will be able to: • Use the standard functions in graphical mapping

Business Example A specific mapping task requires you to use standard functions in a graphical mapping.

Task: You want to create a graphical mapping between the message types Contact1 and Customer1 by using standard functions. 1.

Create a message mapping called ContactToCustomer1. Reference the message type Contact1 as the source structure and the message type Customer1 as the target structure. Both message types are in SWCV SC_BIT_MAP, 1.0 in namespace urn:educationsap.com:bit:mapping (under Basis Objects). Hint: To select the source and target structures, select the message type from the navigation tree and drag it to the relevant field using drag and drop.

2.

Connect source and target fields. Create a graphical mapping between the source fields title, custname, and firstname, and the target field fullname. The three fields should be concatenated in this order with blanks separating them.

3.

Connect source and target fields. Create a graphical mapping between the source field contactID and the target field customerNo. The mapping is to transfer the first 10 digits. An example for the contents of the contactID field is the value 0123456789-181170.

4.

Connect source and target fields. Create a graphical mapping between the source field contactID and the target field birthday. The last six digits of the source field are for the birthday date. It should be stored in the format yyyy/dd/MM.

5.

Connect source and target fields. Continued on next page

2011


57


Exercise Objectives


BIT460

Create an identical graphical mapping between the source fields firstname and custname, and the target fields fullname and surname. 6.

Test the mapping.


58


2011


Use the mapping editor to test function. The field contactID should now have the value 0123456789-181170.

BIT460


Solution 5: Use Standard MessageMapping Functions For internal use by CSC only

You want to create a graphical mapping between the message types Contact1 and Customer1 by using standard functions. 1.

Create a message mapping called ContactToCustomer1. Reference the message type Contact1 as the source structure and the message type Customer1 as the target structure. Both message types are in SWCV SC_BIT_MAP, 1.0 in namespace urn:educationsap.com:bit:mapping (under Basis Objects). Hint: To select the source and target structures, select the message type from the navigation tree and drag it to the relevant field using drag and drop. a)

Create the new message mapping. 1. 2. 3. 4.

Expand the software component version SC_BIT_MAP, 1.0 . In your namespace http://educationsap.com/pi/mapping##, navigate to the Message Mappings node. Create a new message mapping by calling the context menu and choosing New.... Enter the name ContactToCustomer1 and your namespace and choose Create.

b)

Enter a description for the message mapping.

c)

Specify a source message. Drag the Contact1 message type to the field with the label Enter a source message.

d)

Specify a target message. Drag the Customer1 message type to the field with the label Enter a target message

2.

Connect source and target fields.


2011


59


Task:


BIT460

Create a graphical mapping between the source fields title, custname, and firstname, and the target field fullname. The three fields should be concatenated in this order with blanks separating them. For internal use by CSC only

Select the fields to connect. Drag the target field fullname to the data flow editor by using drag and drop. Drag the title, custname, and firstname source fields individually to the data flow editor by using drag and drop.

b)

Select the function to use in the connection. In the lower screen area of the data flow editor, choose Text Functions. Select concat and drag the function to the data flow editor twice by using drag and drop.

c)

Connect the fields in the data flow editor as follows: fullname = concat(concat(title, firstname), custname) To separate the field contents with spaces, double-click both concat functions and enter Space as the parameter.

3.

Connect source and target fields. Create a graphical mapping between the source field contactID and the target field customerNo. The mapping is to transfer the first 10 digits. An example for the contents of the contactID field is the value 0123456789-181170. a)

Select the fields to connect. Drag the customerNo target field to the data flow editor by using drag and drop. Drag the contactID source field to the data flow editor by using drag and drop.

b)

Select the function to use in the connection. In the lower screen area of the data flow editor, choose Text Functions. Select the substring function and drag it to the data flow editor by using drag and drop.

c)

Connect the fields in the data flow editor as follows: customerNo = substring(contactID) Use 0..10 as parameters in the substring function by double-clicking the substring function and setting the Start Position to 0 and the Character Count to 10.

4.



60


2011


a)

BIT460


Create a graphical mapping between the source field contactID and the target field birthday. The last six digits of the source field are for the birthday date. It should be stored in the format yyyy/dd/MM. For internal use by CSC only

Select the fields to connect. Drag the birthday target field to the data flow editor by using drag and drop. Drag the contactID source field to the data flow editor by using drag and drop.

b)

Select the function to use in the connection. In the lower screen area of the data flow editor, choose Text Functions. Select the substring function and drag it to the data flow editor by using drag and drop.

c)

Select the function to use in the connection. In the lower screen area of the data flow editor, choose Date Functions. Select the DateTrans function and drag it to the data flow editor by using drag and drop.

d)

Connect the fields in the data flow editor as follows: birthday = DateTrans(Substring(contactID)) Use 11..17 as parameters in the substring function by double-clicking the substring function and setting the Starting Position to 11 and the Number of Characters to 6. Hint: 11..17 is then displayed in the function display. Use ddMMyy as the source format and yyyy/dd/MM as the target format in the DateTrans function by double-clicking the DateTrans function and entering ddMMyy as the inbound data format and yyyy/dd/MM as the outbound data format.

5.

Connect source and target fields. Create an identical graphical mapping between the source fields firstname and custname, and the target fields fullname and surname.

6.

a)

Drag the firstname target field to the firstname source field by using drag and drop.

b)

Drag the surname target field to the custname source field by using drag and drop. Then save your mapping.

Test the mapping.


2011


61


a)


BIT460

Use the mapping editor to test function. The field contactID should now have the value 0123456789-181170. a)

Create a new XML instance.


b)

Start the message-mapping test. Execute the mapping by choosing Execute Mapping.

62


2011


To create a new XML instance, choose the Test tab page and then Create Instance. Expand the nodes in the XML instance and populate the fields with test values.

BIT460


Lesson Summary


2011



You should now be able to: • Implement standard functions in your own message mappings • Create and implement user-defined functions in message mappings

63

Unit Summary

BIT460

Unit Summary


64



You should now be able to: • Create a message mapping • Use the mapping editor and explain how it works • Test a message mapping • Use trace information to help debug issues that arise during the testing process • Create and test a configuration scenario • Implement standard functions in your own message mappings • Create and implement user-defined functions in message mappings

2011






Advanced Mapping Concepts Unit Overview Unit Objectives After completing this unit, you will be able to: • • • • • • • • •

Create a message mapping that makes use of contexts Set and delete the message-mapping context Use advanced options to help debug the message-mapping process Create user-defined functions and use them in the mapping editor Define and use both local and global user-defined functions Create function libraries and include them in a message mapping Change queues and contexts using standard and user-defined functions Work with mapping objects Output messages in the trace log

Unit Contents Lesson: Using Contexts in Message Mapping ............................... 66 Exercise 6: Create a Message Mapping with Context Handling ...... 83 Lesson: Working with User-Defined Functions .............................. 88 Exercise 7: Create and Use Local User-Defined Functions ..........103 Exercise 8: Create and Use a Function Library ........................ 113 Exercise 9: Work with Local and Global User-Defined Functions ... 117 Exercise 10: Use variables in user-defined functions .................129

2011


65


Unit 3

Unit 3: Advanced Mapping Concepts

BIT460

Lesson: Using Contexts in Message Mapping Lesson Overview For internal use by CSC only


Create a message mapping that makes use of contexts Set and delete the message-mapping context Use advanced options to help debug the message-mapping process

Business Example You are responsible for the development of mappings in SAP NetWeaver Process Integration and require an overview of the advanced message-mapping options that queues and contexts provide.

Message-Mapping Structures and Elements XML structures can contain substructures with multiple occurrences. This multiple occurrence of structures or fields is particularly important when there are source and target structures or fields with varying occurrences. Hint: Even if elements can occur more than once in the XML instance according to XML schema definition, they are only displayed once in the structure overview. In the test area, you can use the context menu to copy individual fields or entire subtrees, which allows you to create and test them with any desired number of occurrences. An icon precedes every field in the structure overview. These icons indicate the status of a field, as illustrated in the following table: Icon Types Used in the Structure View Icon

Meaning Attributes Elements Elements with maxOccurs > 1 Nodes

66


2011


In this lesson, you learn how to use queues, contexts, and advanced options to help improve the message-mapping process.

BIT460

Lesson: Using Contexts in Message Mapping

Figure 18: Status of Fields, Attributes, and Nodes

The information displayed in Status of Fields, Attributes, and Nodes tells us the following about the status of fields and nodes: •

Contactln node: Contains an attribute with the name Type. Both icons are green, which indicates that an assignment was already made.

•

Name node: Contains the two elements, Firstname and Surname. The red icon for both elements indicates that they are mandatory fields, and that values still need to be entered for them. This means the mapping is not yet complete.

•

Surname field: The field must be created and filled only once.

•

Firstname field: The field can be created and filled more than once.

•

Occurrences column: Indicates that all the target structure elements mentioned above must be created and filled at least or exactly once.

•

2011

Address node


67



The figure Status of Fields, Attributes, and Nodes illustrates an example structure with the corresponding icon types and colors.


BIT460

Hint: The icons preceding the Address fields are white indicating that they do not have to be created in the target structure. The following table summarizes the meaning associated with the icon color, for example, green, red, or white. Meaning of Icon Colors Color

Description

White

Attribute or element not assigned

Red

Attribute or element must be assigned to complete the mapping

Yellow

Attribute or element is assigned, but the corresponding mapping in the data flow editor is not complete

Green

Target-field mapping is complete

Hint: The colors are only displayed in the target structure because the mapping is a target-field mapping, responsible for creating a valid target structure. Whether the source structure is valid can be checked with XML validation as a pipeline step (not inside mapping).

Message-Mapping Queues Message mapping is performed at runtime using queues. A queue contains all values relating to a field in the message mapping. There is a queue for each XML hierarchy level. If you have created an XML instance in the test environment editor, you can display the various queues in the data flow editor. The following queues can exist at message-mapping runtime: •

Source Structure: A queue exists for each field in the source structure.

•

Input and Result Queues: Standard and user-defined functions process the input queues and write the result of a calculation to a result queue; the result queue of one function can also serve as the input queue for another function.

•

68

Target Fields:


2011



The Address node and its subelements Street, CityCode, City, Phone, and Email can be created in the target structure, since the minimum number of occurrences is 0.

BIT460


A queue exists for the target field; the limitations of the target fields determine which values from the target-field queue are written in the target structure.


The queue concept enables large XML messages to be processed quickly, since the entire XML tree does not need to be built each time, only the values of a hierarchy level. This can be done using a SAX parser; a DOM parser (which builds the entire XML tree for an XML file) would use both too much memory and CPU time.

Input Queues with Different Lengths If a source structure contains more than one instance of the same elements (occurrence > 1), the context of a queue can contain multiple values. As long as the input queues have the same number of values for each context, the way the values are processed is clear-cut:

Figure 19: Queues with the Same Contexts

The input queues for the concat function in the following example have a different number of values in the related contexts. If, for this reason, an input value from a queue is missing for a function, the message mapping runtime simply uses the last value that was read from the queue:

2011


69


Hint: Each field is determined by the field name and the structure hierarchy in which it exists. If two fields have the same name but occur on different levels (“paths”) then two separate queues are created.

BIT460

Figure 20: Queues with Different Contexts

Hint: In both figures, the queues are read from right to left, which means the values 1 and a are processed first. The same also applies to generating functions (such as constants) that only generate one value when they are linked to a function. If an additional input queue has more than one value in a context, the mapping runtime simply reuses the last value returned by the generating function.

Message-Mapping Contexts The context of a field can also be understood as a type of association, that is, as a description of the structure or hierarchy in which the field occurs. A field can contain multiple contexts if the field exists in a series of structure levels in a hierarchical manner. If a field is part of a structure that can have multiple occurrences (occurrences > 1), this is referred to as a context change for the field. Hint: If a field occurs more than once (occurrence > 1) within one structure, this does not constitute a context change, since the field occurs more than once within the same structure (that is, the same context). If there is a context change within the hierarchy, this is shown in the relevant queue. This concept is illustrated in detail in the figure Context Changes in XML Files. For the item element, for example, there are two context changes, since the item element occurs in the context of three nodes with the name A. This results in two context changes for the queue on the hierarchy level of the item element.

70


2011





Figure 21: Context Changes in XML Files

The figure Complex Example of a Context Change illustrates the concept of context change in more detail for a field “person” using the following contexts: •

Apartment Context: In the context of the first apartment, Fix and Foxy are the people who live there. There are four apartments in total, therefore three context changes.

•

Street Context: In the context of the first street, Fix, Foxy, Jolly Jumper, and Lucky Luke are the residents. There are three streets in total, therefore two context changes.

•

City Context: In the context of the first city, Asterix, and Obelix are also residents. There are two cities in total, therefore one context change.

•

Root Context: Valerian is only a resident in the context of the root element root. There is no context change in this context.

2011


71



BIT460

BIT460

Figure 22: Complex Example of a Context Change

Context changes can be created and deleted with both standard functions and user-defined functions. This enables a direct influence on the hierarchy levels in the source message. User-defined functions are explained in more detail in subsequent lessons.

Context Selection and Deletion The mapping editor provides a selection of standard functions that you can use to manipulate contexts (for example, to set and delete them), as follows: •

RemoveContexts() Deletes all context changes in a queue.

•

SplitByValue() Inserts an additional context change after any value, any value change, or any empty entry. You select one of these three options by setting the relevant property in the function.

The standard function SplitByValue() can be regarded as the inverse function of RemoveContexts(). Hint: Values can only be filled in open contexts; otherwise values are lost. Open contexts are generated when the parent node is created.

72


2011




BIT460


The figure Impact of the Standard Function RemoveContexts() on the Message Mapping illustrates how the standard function RemoveContexts() works: •

RemoveContexts() Example 1:


•

RemoveContexts() Example 2: In the second example illustrating the standard function RemoveContexts(), the context change is deleted by RemoveContexts(), which means the contents of all the item source fields are transferred to the queue without a context change. As a result, the transferred fields are all created as item target fields and their values transferred accordingly.

Figure 23: Impact of the RemoveContexts() Standard Function on Message Mapping

2011


73


In the first example for ,the standard function RemoveContexts() only the values for the source field item of the first node header are used. The mapping program creates the corresponding item target fields, and the contents of the source fields are copied. In this case, the mapping stops (for this field) at the first context change because node A can only occur once in this example.


BIT460

The figure Impact of the Standard Function SplitByValue() on the Message Mapping illustrates how the standard function SplitByValue() works. •

SplitByValue() is not used:


•

SplitByValue() is used: In the second example, SplitByValue() is used which results in a context change after each source element item. Every target element item appears in an individual context new_context.

Figure 24: Impact of the Standard Function SplitByValue() on the Message Mapping

Explicit Context Selection You can set the context of source fields explicitly in the data flow editor using the menu displayed by clicking the secondary mouse button. The figure Impact of Explicit Context Selection in the Message Mapping illustrates the effect on the sample message type TestContext. Depending on whether you select segment, parent, or TestContext as the context for the item source field, the queue has either 4, 1, or no context changes. If a higher context level is selected, the context

74


2011


In the first example, four context changes are generated as required. However, after the first context change, all four item source fields are saved as item target fields and then populated with the relevant strings.

BIT460


changes located under this level are deleted. This method provides an elegant way of solving the task of context selection for source fields, and enables users to avoid multiple use of the standard function RemoveContexts() in the message mapping. For internal use by CSC only


Figure 25: Impact of Explicit Context Selection in the Message Mapping

However, the function RemoveContexts() still has its advantages, since it proves useful in target-field mappings comprised of function chains. You use the exists() standard function to determine whether a particular source field exists in the XML instance being processed. If it does, exists() returns true; if it does not, it returns false. This is useful, for example, if you want to map an optional source field to an obligatory target field because you can check whether the field (not the contents) actually exists and if necessary, transfer a constant instead. The last standard function discussed here is copyValue(). For a field with an occurrence of > 0, this function enables you to copy the individual values separately to multiple target fields. If a source structure contains a field with the name addrDat and the field has three values, you can map these three values to the street, city, and zipcode target fields by using copyValue() (and specifying an index): /ns0:MT_B/street=CopyValue(/ns0:MT_A/addrDat, nnumber=0) /ns0:MT_B/city=CopyValue(/ns0:MT_A/addrDat, nnumber=1) /ns0:MT_B/zipcode=CopyValue(/ns0:MT_A/addrDat, nnumber=2)

2011


75


BIT460

Target Structure Generation


•

Source structure: The number and type of tags that exist in the source-structure instance

•

Target structure: The number of occurrences specified for the target fields in the target structure

Whether the mapping program creates a particular structure field in the target structure depends on the number of occurrences in the target structure and whether a target-field mapping has been defined for this field. The following table provides an overview of when you have to define target-field mappings for structure fields according to the schema definition for the target structure. Target-Field Mappings Required for Structure Fields in the Target Structure Occurrence

Conditions for Creation

n = minOccurs = maxOccurs > 0

The message mapping creates these structure fields automatically because they must occur n times in the target structure independent of the target-field mapping. You can still assign a target-field mapping to structure fields of this type. The structure field is optional. Whether it is created depends on whether you have assigned it a target-field mapping. The following applies here:

minOccurs = 0

•

76

When you assign a target-field mapping to the structure field, you also have to do this for mandatory subelements/attributes, otherwise the message mapping is incomplete.


2011


In the mapping editor, you assign the fields of two XML structures to each other. Note that at runtime no target structure exists prior to the mapping. The mapping program creates the target structure only during execution of the mapping. This means that the message mapping has to create the target structure at runtime. Two things determine how the target structure looks after it has been created:

BIT460


0 < minOccurs < maxOccurs

To create optional structure fields, it is not sufficient to create a target-field mapping for subelements/attributes. The message mapping suppresses optional structure fields without target-field mappings including subnodes.

You must define a target-field mapping for structure fields of this type. How often these structure fields are created depends on the minOccurs, maxOccurs, and target-field mapping.

Hint: Before a node with minOccurs = 0 can be created in the target structure, the message mapping must contain a function to create it, for example, one of the standard functions that belong to the Constants function category. A simple mapping example should clarify the issues described above. The following figure shows the source and target structures and the corresponding mapping.

Figure 26: Creating the Target Structure - A Simple Mapping Example

To show more clearly how the target structure is created, an actual message from a sender system is used here as a basis for creating the target fields.

Figure 27: Creating the Target Structure - Source Message

2011


77



•


BIT460

Figure 28: Creating the Target Structure - Number of Occurrences: minOccurs = maxOccurs = 1

The number of occurrences for node B is between minOccurs = 0 and maxOccurs = unbounded. However, since a target-field mapping is defined for node B, the mapping program creates it in the target structure as often as required according to the source structure and target-field mapping (in this case, three times).

78


2011



Even though the MT_TargetMessage node has no target-field mapping, the mapping program creates this node exactly once to match the number of occurrences specified.




BIT460

Figure 29: Creating the Target Structure - Number of Occurrences: minOccurs = 0

Hint: The attribute setting minOccurs > 0 for a field does not necessarily mean that the field will be existing in the target message. Assuming that the field is part of a structure node with minOccurs = 0, and if no mapping is assigned to that structure, neither the structure nor the subordinate fields are created. In the example, this applies to node B and field item. The number of occurrences for the item target field is between 1 and unbounded. In practice, however, this field cannot be created an infinite number of times. How often the mapping program creates this field in this case ultimately depends on the corresponding source fields, how often they occur, and the relevant target-field mapping.

2011


79

BIT460




Figure 30: Creating the Target Structure - Number of Occurrences: 0 < minOccurs < maxOccurs

The Message-Mapping Debug Process Using the mapping editor, you can debug all steps in a message mapping by displaying the contents of the relevant queues. For each element in the data flow editor (both fields and functions) you can display the contents of the queue by choosing Display Queue in the secondary mouse click (context menu). Hint: Note that the term context menu refers to the menu that you navigate to by right-clicking. The term context has two different meanings here. The message mapping in the figure Message Mapping for the Target Field Description illustrates an example of a more complex message mapping for the target field Description.

80


2011


Figure 31: Message Mapping for the Target Field Description

First of all, the source field LANGKEY is compared with the constant EN. If this comparison is successful, the contents of the source field TEXT are copied to the target field Description. The figure Debugging View of the Target-Field Mapping Description illustrates the contents of the corresponding queue. Based on the contents of the queue equalsS the value [true] is only determined in the second case. This means that the content toothpaste is copied from the middle field TEXT to the target field Description. This result is represented in the queue for the IfWithoutElse element.

Figure 32: Debugging View for the Description Target-Field Mapping

2011


81



BIT460


BIT460

The displayed queue contains the following entries: •

Initial Context change: The first gray entry represents the initial change that is not part of the contents of the queue.

•

Final context change: The last black entry represents final context changes that is not part of the contents of the queue.

•

Suppressed entries: The two turquoise entries are the suppressed entries; they result from the [false] entries of the “if” part of the IfWithoutElse standard function.

82


2011



In this example, it becomes visible that debugging of message mappings is performed by displaying the queue. The result from each step of the message mapping is represented in such a way that you can examine the transformation from the source fields to the target fields in a step-by-step manner.

BIT460


Exercise 6: Create a Message Mapping with Context Handling For internal use by CSC only

After completing this exercise, you will be able to: • Use contexts in a message mapping • Use queues to help debug and test a message mapping

Business Example A specific mapping task requires you to use queues and contexts to check a message mapping.

Task: Map a source message containing material data, a material number, and descriptions in various languages to a target message containing the material number and the description of the material in English. 1.

Create a message mapping with the name MaterialToProductDefinition for software component version SC_BIT_MAP 1.0 in your namespace http://educationsap.com/pi/mapping##. The message mapping must reference the message type MATERIAL as the source structure and the message type ProductDefinition as the target structure.

2.

Transfer the source field to the target field. The message mapping requires that you first transfer the source field MATNO to the target field RefNo. You then need to check the source field LANGKEY for EN and copy the corresponding contents of the source field TEXT to the target field Description.

3.

Test the new message mapping. Use the mapping editor test function to test the message mapping. For the purposes of the test, create at least three different entries for the MATTEXT node, and give each of them different values for the LANGKEY field, one of which must be EN. Display the resulting queues.

4.

2011

Change the language for the Langtext of the material and test the mapping again.


83


Exercise Objectives


BIT460

Solution 6: Create a Message Mapping with Context Handling For internal use by CSC only

Map a source message containing material data, a material number, and descriptions in various languages to a target message containing the material number and the description of the material in English. 1.

Create a message mapping with the name MaterialToProductDefinition for software component version SC_BIT_MAP 1.0 in your namespace http://educationsap.com/pi/mapping##. The message mapping must reference the message type MATERIAL as the source structure and the message type ProductDefinition as the target structure. a)

Create a new message mapping. In your namespace http://educationsap.com/pi/mapping##, navigate to the Message Mappings node. Create a new message mapping by calling the context menu and choosing New.... Enter the name MaterialToProductDefinition and your namespace and choose Create. Enter a description.

b)

Choose the source and target messages. Drag the MATERIAL message type to the field with the label Choose a Source Message. Drag the ProductDefinition message type to the field with the label Choose a Target Message.

2.

Transfer the source field to the target field.


84


2011


Task:

BIT460


a)

Map source and target fields. Create an identical mapping between the source field MATNO and the target field RefNo. Drag the RefNo target field to the MATNO source field by using drag and drop.

b)

Load the mapped fields into the data flow editor. Load the Description target field into the data flow editor by double-clicking it. Drag the TEXT and LANGKEY source fields to the data flow editor by using drag and drop.

c)

Set the mapping context. Set the context for the source fields TEXT and LANGKEY to Material by choosing Context → MATERIAL in the context menu.

d)

Select the Text and Boolean message-mapping functions. From the Text function category, choose the equalsS function, and from the Boolean Functions area, choose the IfWithoutElse function, and drag them to the data flow editor using drag and drop.

e)

Select the Constant message-mapping function. Select the Constant function from the Constant Functions area and drag it to the data-flow editor by using drag and drop.

f)

Connect source and target message-mapping fields. Connect the fields in the data flow editor as follows: Description = IfWithoutElse(equalsS(LANGKEY, Constant), TEXT) Choose EN as the parameter for the Constant function by double-clicking the Constant function and entering EN as the parameter. Save your mapping.

3.

Test the new message mapping.


2011


85



The message mapping requires that you first transfer the source field MATNO to the target field RefNo. You then need to check the source field LANGKEY for EN and copy the corresponding contents of the source field TEXT to the target field Description.


BIT460

a)

Create a new XML instance. Choose the Test tab page and create a new XML instance by choosing Generate Instance. Create at least three different entries for the MATTEXT node by clicking Duplicate Subtree with the secondary mouse button. Expand the nodes in the XML instance and populate the fields with test values.

b)

Start the message mapping. Start the mapping by choosing Execute Mapping. Choose Design and double-click the target field Description. Call the context menu for the functions displayed in the data-flow editor and choose Display Queue. Track the contents of the queue for the entire message mapping.

4.

Change the language for the Langtext of the material and test the mapping again. a)

Confirm the message-mapping mode. Make sure that the message mapping is in change mode.

b)

Display the message mapping for the target field. Open the existing mapping for the target field Description by double-clicking the field to load it into the data flow editor.

c)

Edit the Constant function. Open the editor for the Constant function by double-clicking the field, change the displayed value from EN to (for example) FR, and close the editor.

d)

Start the message mapping. Repeat the message-mapping test as outlined in the previous step.

86


2011



Use the mapping editor test function to test the message mapping. For the purposes of the test, create at least three different entries for the MATTEXT node, and give each of them different values for the LANGKEY field, one of which must be EN. Display the resulting queues.

BIT460


Lesson Summary


2011



You should now be able to: • Create a message mapping that makes use of contexts • Set and delete the message-mapping context • Use advanced options to help debug the message-mapping process

87


BIT460

Lesson: Working with User-Defined Functions For internal use by CSC only

This lesson shows how to use the mapping editor to employ user-defined functions in message mappings. The lesson illustrates the difference between local user-defined functions and global user-defined functions, which are created in function libraries. The lesson also describes how you can use user-defined functions to change queues and contexts.

Lesson Objectives After completing this lesson, you will be able to: • • • • • •

Create user-defined functions and use them in the mapping editor Define and use both local and global user-defined functions Create function libraries and include them in a message mapping Change queues and contexts using standard and user-defined functions Work with mapping objects Output messages in the trace log

Business Example You are responsible for the development of mappings in SAP NetWeaver Process Integration. You need to understand how to use advanced message-mapping options to map field contents, including those for source and target structures with different numbers of occurrences. You also need to know how to enhance standard message-mapping functions with your own user-defined functions (and various objects) to automate particular aspects of the message-mapping process.

User-Defined Message-Mapping Functions If the existing standard functions do not fulfill the requirements for your message-mapping needs, you can create your own user-defined functions in the mapping editor. The functions contain Java source code that Enterprise Services Repository saves for use in message mapping. Internally, the function is included as a Java method in the Java code generated for the message mapping.

88


2011


Lesson Overview

BIT460

Lesson: Working with User-Defined Functions

The parameters of a user-defined function such as the name, title, description, and execution type are important. •

Function name:


•

Function title: The name of the function in the data flow editor

•

Execution type: Controls how the function behaves during message mapping

You create user-defined functions in the Functions tab of the message mapping. You can define the number, names, and types of function transfer arguments in the Signature Variables area. Once you have created a user-defined function, you can use it in the Design tab (in the data flow editor) in the same way you would use a standard function. The only difference is that the new user-defined function is displayed in the User-Defined area in the list of standard functions. Hint: You may define your own Category instead of User-defined. The following figure shows how to create a user-defined function.

Figure 33: Creating User-Defined Functions in the Data-Flow Editor

A user-defined function is a Java method with an interface, consisting of the parameters that you enter and the Container object. A user-defined function can have multiple parameters, which are listed as method parameters in the editor

2011


89


The technical name (the name of the Java method)


BIT460

window. You can use these parameters in the Java code by entering the names specified in the interface (Name string, Surname string, ...). In this example, the result must be returned as a string via return (depending on the Execution Type. For internal use by CSC only

After you create a function, it is displayed in the Functions selection in the data flow editor. You can delete or edit functions at any time, either in the Functions tab, or in the Design tab, in the data flow editor. Testing the message mapping (menu Message Mapping - Check or F7) will check the java source code

Local and Global Functions You can enhance the standard message-mapping functions by defining your own additional local functions. A local user-defined function is only visible in the message mapping for which the function was created. You can also define global user-defined functions that are stored in function libraries and available to all message mappings. A message mapping can include all global function libraries and use their functions, which are themselves defined in the same software-component version as the message mapping or an underlying version. The overall process for defining a global user-defined function is as follows: 1. 2. 3. 4.

Create a function library. Define user-defined functions in the function library. Include the function library in the message mapping. Use (global) user-defined functions from the function library in the message mapping.

Functions Libraries A function library is a separate object type in Enterprise Services Repository and can therefore be created via the context menu of, for example, a namespace or software component version, for example: Context menu → New → Mapping Objects → Function Library. You must assign a name to the function library and then assign the function library to a software component version and one of the namespaces contained therein. Hint: You must ensure that the function library is located in the same software component version as the message mappings you want to use or an underlying version.

90


2011


The figure above provides a simple example of the source code for a user-defined function. The three input parameters are typed as String, are merged into one string, and then returned by the function via return.

BIT460


You define functions in the function library by making an entry in “Functions and Java Areas” and giving the function a name. You can maintain the function parameters and source code in the same way as for local user-defined functions, as illustrated in the figure below. For internal use by CSC only


Figure 34: Creating a (Global) User-Defined Function in a Function Library

After you create global user-defined functions in a function library, you can use them in a message mapping. You can include function libraries in your message mapping by making an entry in Used Function Libraries and using the input help to select the function library required. The selected function library appears in the Functions list in the mapping editor. When you select the function library from the list, all the functions defined there appear in the mapping editor as pushbuttons and can be used for the individual target-field mappings.

2011


91

BIT460




Figure 35: Including Function Libraries in Message Mappings

Function Execution Types When you create a user-defined function, you can use the Execution Type function parameter to control how the function works internally. You can choose between the execution types described in the following table:

92

Execution Type

Description

Single Values

All entries in an inbound queue are processed individually, that is, the function is called internally as many times as there are entries in the inbound queue. The function returns a single value (string).

All Values of Context

All values belonging to one context in an inbound queue are processed together. The function is called as many times as there are contexts in the inbound queue and each context is transferred to the function as a string array. The function returns a string array via the result outbound parameter (of type ResultList).

All Values of Queue

All values in an inbound queue are transferred to the function together, that is, the function is executed only once internally. The inbound queue is transferred to the function as a string array. The function returns a string array in the result outbound parameter (of type ResultList).


2011

BIT460


Figure 36: Effect of Different Execution Types on User-Defined Functions (UDF)

Hint: Note that when large messages are processed, much cache memory is required at runtime to save the entire queue. In such cases, it is better to work with contexts. The name of the Execution Type parameter has changed over the last few releases. The table below shows the names used in the individual releases of SAP NetWeaver Process Integration:

2011

Release

3.0

7.0

7.1 and above

Name

-

Cache

Execution Type

1. execution type

Simple function

Value

Single Values

2. execution type

Enhanced function

Context

All Values of Context

3. execution type

Enhanced function with “Save Entire Queue in Cache” indicator

Queue

All Values of Queue


93



The following figure illustrates the concept of execution types using an inbound queue as an example. The example shows how many times the function was called internally for each of the execution types.


BIT460

Result Queues and Parameters


•

ResultList class methods: – void addValue(String value) – void addContextChange() – void addSuppress()

•

– void clear() ResultList class constants: – String ResultList.CC (context change) – String ResultList.SUPPRESS (hidden element)

The addContextChange method appends the ResultList.CC constant to the list (in Java, this is a static variable). The addSuppress method appends the ResultList.SUPPRESS constant to the list. You cannot generate the target field and its sub nodes for entries such as these. The following example illustrates how the ResultList class methods and constants are used; the example looks at the copyPerValueWithQueue function, which has two input parameters (var1 and var2). Based on the entries for var2, it is assumed that a context only ever contains one value that is to be reproduced in the outbound queue. The reproduction of var2 shall be done as many times as there are entries in the corresponding context in the queue of the var1 input parameter. This means that, in this example, the following is true: •

Input parameter: Berlin The entry Berlin from var2 is created in the result queue three times because the first context for var1 has three entries.

•

Input parameter: Mühlenhof The entry Mühlenhof is created in the result queue twice because the second context for var1 has two entries.

Since the function in this example has execution type All Values of Queue, the inbound queues also contain all context changes represented in the string array by the constant ResultList.CC. For this reason, it is essential to check within the function whether the current line in the string array for parameter var1 refers to a context change. If it does, a context change must also be carried out in the inbound queue of parameter var2.

94


2011


If you create functions either of execution type All Values of Context or All Values of Queue, you have to create the result queue (or parts of it) in the function yourself using the result parameter. To help you, the ResultList Java class provides methods and constants that you can use in the function.

BIT460



Figure 37: Example of a User-Defined Function with Execution Type All Values of Queue

When the inbound queue is transferred to a function, the first and last context changes are suppressed, that is, the string array always starts and ends with an entry for the relevant field. This also applies for the outbound queues to be created; the first and last entries in the result string array must not be context changes. Hint: In the mapping editor, context changes are indicated by dark gray bars in the queues. However, the values of the previous entries are also displayed in these bars, which may cause confusion at first.

Objects in user-defined functions In addition to the parameters you define yourself, you can use a number of objects belonging to the interface of user-defined functions to make additional generic functions available. The following list shows some of the more commonly used objects: •

Container: The Container object can be used to create an AbstractTrace object as well as a Map object.

•

2011

AbstractTrace:


95


The outbound queue is set up using the addValue method of the result object, which simply attaches the transferred single value to the outbound queue (string array). The mapping task requires all values in the outbound queue to be separated by a context change. You do this using the addContextChange method of the result object.


BIT460

Transfer messages to the mapping trace. The trace is visible in message monitoring, depending on the trace level. •

Map (runtime constants):


•

GlobalContainer: You can use this object to cache the values that you want to read again when you next call any user-defined function in the same message mapping. Hint: Similar goals can be achieved with the Java Sections, so the GlobalContainer will not be discussed in detail.

Container Object The Container object belongs to the interface of user-defined functions, which means you use the object to make available additional objects and user-defined parameters. The methods for the Container object are outlined in the following table. Methods of the Container Class Method

Use

void setParameter (String parName, Object obj);

Save parameters

Object getParameter(String parName);

Read parameters

GlobalContainer getGlobalContainer();

Create a GlobalContainer

AbstractTrace getTrace();

Create an AbstractTrace object

java.util.Map getTransformationParameters()

Create a Map object

Trace Objects In user-defined functions, you can use the AbstractTrace object to transfer messages to the mapping trace. To create an AbstractTrace object, call the getTrace() method for the container object.

96


2011


Access message mapping runtime constants.

BIT460


Method

Use

void addInfo(String message);

Transfer a message to the mapping trace with trace level info

void addWarning(String message);

Transfer a message to the mapping trace with trace level warning

void addDebugMessage(String message);

Transfer a message to the mapping trace with trace level debug

Examples of Trace Messages from a User-Defined Function ... AbstractTrace at = container.getTrace(); at.addInfo( "This is an information" ); at.addWarning( "This is a warning!" ); at.addDebugMessage( "This is a debug message" ); ...

You can display the messages that you write to the trace with these methods in the test environment, for example. You can also set a trace level for each pipeline so that the trace messages are written to the trace header of the message at runtime. The trace levels 0 to 3 are associated with the trace levels info, warning, and debug as follows: Trace Level of the Pipeline and Mapping Trace Pipeline

Mapping Trace

0

No trace

1

addWarning() entries written to trace

2

addWarning() and addInfo() entries written to trace

3

addWarning() and addInfo() and addDebugMessage() entries written to trace

Map Objects A map object enables you to access message-mapping runtime constants. Some mapping programs need to access fields in the message header. To facilitate this, the mapping runtime stores the values of the fields as key-value pairs.

2011


97



Methods of the AbstractTrace Class


BIT460

Key

Value

“MessageClass”

“ApplicationMessage”

“ProcessingMode”

“synchronous”

“ReceiverNamespace”

“http://demo.com/xi/example”

To read the fields of the message header at runtime, you must access the map for the runtime constants. However, accessing the map using the key literals listed above would render the program code invalid if a key is changed at some point in the future. As an alternative, the mapping API provides string constants that you can use instead of key literals to access the map. Examples of Runtime Constants String Constants

Key

Meaning

SENDER_SERVICE

“SenderService”

Sender service

RECEIVER_NAME

“ReceiverName”

Receiver interface

INTERFACE

“Interface”

Sender interface

You can use the map object to access runtime constants in user-defined constants. The map object is created using either the Container object or a GlobalContainer as illustrated in the following code example:

Accessing the Map Object String headerField; java.util.Map map; map = container.getTransformationParameters(); headerField = (String) map.get( StreamTransformationConstants.INTERFACE_NAMESPACE); AbstractTrace at = container.getTrace(); at.addInfo(headerField); return a;

Hint: The user-defined function's input parameter (string a) is returned unchanged. The parameter is only used to allow the function to be called and executed; in this particular example, the assigned value is not changed.

98


2011



Examples of Key-Value Pairs in the Map for Runtime Constants

BIT460


Java Sections


The Java sections can be found in the message mapping on the Functions tab page. Here you can define, for example, the interface of the init method and the source code.

Figure 38: Java Sections in Message Mapping

Java sections do not exist only in (local) user-defined functions; every function library has its own Java sections. If you use multiple function libraries in one message mapping, there are multiple areas in which attributes and methods are defined, as well as multiple init and cleanUp methods. This source code is run either at the start or end of the mapping runtime based on the order in which you have entered the relevant function libraries in the table that defines library usage.

External Java Classes You can also use external classes in user-defined functions. These classes are developed in one package, for example in the SAP NetWeaver Developer Studio, compiled and then exported as JAR files from SAP NetWeaver Developer Studio. These JAR files can then be uploaded to Enterprise Services Repository in an

2011


99


When you create a local user-defined function in a message mapping, the system creates a Java class in the background. You can define attributes in this Java class that can then be used in all user-defined functions for this message mapping. When this class is created, two methods are also created automatically: init and cleanUp. When the mapping is run, these two methods are called automatically: init is called prior to the message mapping and cleanUp is called afterwards, for example, to remove data from the memory that is no longer required once the message mapping is complete. Initially, neither method contains source code, but you can program this yourself.


BIT460

imported archive. In the figure below, a class called myClass is uploaded from the myPackage package to imported archive IA_MyPackage as JAR file extJavaClass.jar. For internal use by CSC only


Figure 39: Importing Externally-Developed Java Classes Using Imported Archives

Hint: Imported archives can be used in a message mapping or function library if they come from the same software component version or an underlying version. After Java classes have been imported in this way, you can use them in the message mapping by entering the relevant imported archive in the message mapping in the Archives Used area on the Functions tab page. You then have to specify the relevant class and package name in the Import Instructions area. You can then use all the methods of this class in the user-defined methods for the message mapping. In the following example, the addCounter method of the imported class myClass is to be used in the user-defined function addCounter. First, go to the Archives Used area and enter the imported archive IA_MyPackage mentioned above. Then go to the Import Instructions area and enter the package and class name myPackage.myClass.

100


2011




BIT460

Figure 40: Using External Java Classes in User-Defined Functions

Hint: Complex user-defined functions should be developed in SAP NetWeaver Developer Studio, for example, and then imported as described above. This is because SAP NetWeaver Developer Studio has a debugger function and test environment.

2011


101


BIT460



102


2011

BIT460


Exercise 7: Create and Use Local User-Defined Functions For internal use by CSC only

After completing this exercise, you will be able to: • Create and use local user-defined functions in a message mapping

Business Example A specific mapping task requires you to use queues, contexts, and user-defined functions in message mapping.

Task: The source message contains purchase order information. It can contain multiple purchase orders. Each purchase order has header information and several ordered objects. The target message is a table containing the same number of rows as there are ordered objects. Each row contains the relevant header information for the corresponding purchase order. This kind of mapping program is very useful for processing IDocs in tables. Here, too, the header information has to be added for each IDoc entry in the row. There are numerous ways to handle this mapping task. The solution described here is just one of these many possibilities. 1.

Create a new message mapping. Create a message mapping with the name PurchaseOrderToResultset in software component version SC_BIT_MAP, 1.0 in your namespace http://educationsap.com/pi/mapping##. In the message mapping, reference the message type PurchaseOrder as the source structure and the message type resultset as the target structure.

2.

Map the message fields. Create an identical mapping between the source and target fields Material, Units, and Price.

3.

Remove context of source object item. To create exactly the same number of rows row as objects item, you have to move the source field item from its context in the message mapping and connect it to the target field row.

4.

Create a user-defined function with the name copyPerValue.


2011


103


Exercise Objectives


BIT460

5.

Define the user function. Combine the copyPerValue function with the source fields Name and Address and the SplitByValue function so that the correct number of target fields name and address are created in the target structure.

6.

Test the mapping by using the mapping editor test function.

7.

Additional Task I: Create another user-defined function and name it copyPerValueWithQueue. In this function, do not use the SplitByValue function as you did in Step 6, but enter the relevant code to handle the context changes in the source text.

8.

Additional Task II: Instead of your user-defined function copyPerValue, use the standard function useOneAsMany for the Name target-field mapping.

104


2011



To make sure that the header entries of the individual source objects are copied enough times, you can create a user-defined function with the name copyPerValue. You use that function to copy any source field to an array, as specified by the number of item source fields.

BIT460


Solution 7: Create and Use Local User-Defined Functions For internal use by CSC only

The source message contains purchase order information. It can contain multiple purchase orders. Each purchase order has header information and several ordered objects. The target message is a table containing the same number of rows as there are ordered objects. Each row contains the relevant header information for the corresponding purchase order. This kind of mapping program is very useful for processing IDocs in tables. Here, too, the header information has to be added for each IDoc entry in the row. There are numerous ways to handle this mapping task. The solution described here is just one of these many possibilities. 1.

Create a new message mapping. Create a message mapping with the name PurchaseOrderToResultset in software component version SC_BIT_MAP, 1.0 in your namespace http://educationsap.com/pi/mapping##. In the message mapping, reference the message type PurchaseOrder as the source structure and the message type resultset as the target structure. a)

Create the new message mapping: In your namespace http://educationsap.com/pi/mapping##, navigate to the Message Mappings node. Create a new message mapping by calling the context menu and choosing New.... Enter the name PurchaseOrderToResultset and your namespace and choose Create.

b)

Select the message types to map. Enter a description. Drag the PurchaseOrder message type to the field with the label Enter a source message. Drag the resultset message type to the field with the label Enter a target message.

2.

Map the message fields.


2011


105


Task:


BIT460

3.

a)

Drag the material target field to the Material source field by using drag and drop.

b)

Drag the units target field to the Units source field by using drag and drop.

c)

Drag the price target field to the Price source field by using drag and drop.

Remove context of source object item. To create exactly the same number of rows row as objects item, you have to move the source field item from its context in the message mapping and connect it to the target field row. a)

Load the source and target fields. Load the row target field into the data-flow editor by double-clicking it. Drag the item source field to the data-flow editor by using drag and drop.

b)

Locate the removeContexts function. In the lower screen area of the data-flow editor, choose Node Functions. Select the removeContexts function and drag it to the data-flow editor by using drag and drop.

c)

Include the removeContexts function. Connect the fields in the data-flow editor as follows: row = removeContexts(item)

4.

Create a user-defined function with the name copyPerValue.


106


2011



Create an identical mapping between the source and target fields Material, Units, and Price.

BIT460


a)

Create the user-defined function copyPerValue. Create a user-defined function by selecting the relevant icon in the toolbar at the bottom of the data-flow editor. Enter copyPerValue as the name and copyPerValue as the title to appear in the data-flow editor. Fill the Description field and set the Execution Type field to All Values of Context. Using the first icon, insert a second argument var2 of type string after argument var1. Choose Create Function.

b)

Define the user function copyPerValue. Enter the following source code in the new user-defined function : for (int i=0; i
c)

Save the user-defined function copyPerValue. Choose Close and save your mapping.

5.

Define the user function.


2011


107



To make sure that the header entries of the individual source objects are copied enough times, you can create a user-defined function with the name copyPerValue. You use that function to copy any source field to an array, as specified by the number of item source fields.


BIT460

Combine the copyPerValue function with the source fields Name and Address and the SplitByValue function so that the correct number of target fields name and address are created in the target structure. For internal use by CSC only

Specify source and target fields. Load the name target field into the data-flow editor by double-clicking it. Drag the source fields Name and item to the data-flow editor by using drag and drop.

b)

Specify a user-defined function. In the lower screen area of the data-flow editor, choose User-Defined Functions. Select the copyPerValue function and drag it to the data-flow editor by using drag and drop.

c)

Specify a node function. In the lower screen area of the data-flow editor, choose Node Functions. Select the SplitByValue function and drag it to the data-flow editor by using drag and drop.

d)

Define the function usage. Connect the fields in the data-flow editor as follows: name = SplitByValue(copyPerValue(item, Name))

e)

Specify source and target fields. Load the address target field into the data-flow editor by double-clicking it. Drag the source fields Address and item to the data-flow editor by using drag and drop.

f)

Specify a user-defined function. In the lower screen area of the data-flow editor, choose User-Defined Functions. Select the copyPerValue function and drag it to the data-flow editor by using drag and drop.

g)

Specify a node function. In the lower screen area of the data-flow editor, choose Node Functions. Select the SplitByValue function and drag it to the data-flow editor by using drag and drop.

h)

Define the function usage. Connect the fields in the data-flow editor as follows: address = SplitByValue(copyPerValue(item, Address)) Save your mapping.


108


2011


a)

BIT460


6.

Test the mapping by using the mapping editor test function. a)

Create a new XML instance.


b)

Start the test. Execute the message-mapping test by choosing Start Transformation.

7.

Additional Task I: Create another user-defined function and name it copyPerValueWithQueue. In this function, do not use the SplitByValue function as you did in Step 6, but enter the relevant code to handle the context changes in the source text. a)

Create a user-defined function. Create a user-defined function by choosing the relevant icon beside the Functions text in the lower toolbar of the data-flow editor. Select copyPerValueWithQueue as the name and copyPerValueWithQueue as the title. Fill the Description field and set the Execution Type field to All Values of Queue. Using the first icon, insert a second argument var2 of type string after argument var1. Choose Create Function.

b)

Define the new user function. Enter the following source code: int var2_counter = 0; for ( int i=0; i
c)

Save the message mapping Choose Close to save the changes to your message mapping.

d)

Delete the mapping for the address target field. Continued on next page

2011


109


Choose the Test tab page and create a new XML instance by choosing Create Instance. Expand the nodes in the XML instance and use the context menu to copy the Order node once and the item node at least once for each order. Fill all fields in the XML instance with test values, choose Add Test Instance, and save this test message as a test case Test1 for use in later tests.


BIT460

e)

Select the source fields to map. Drag the source fields Address and item to the data-flow editor by using drag and drop.

f)

Select the user-defined function. In the lower screen area of the data-flow editor, choose User-Defined Functions. Select copyPerValueWithQueue and drag the function to the data-flow editor by using drag and drop.

g)

Assign the user function. Connect the fields in the data-flow editor as follows: address = copyPerValueWithQueue(item, Address)

h)

Save the message mapping.

i)

Test the message mapping. Choose the Test tab page and use the test case already created to test your change by choosing Start Transformation.

8.

Additional Task II:


110


2011



Load the target field into the data-flow editor by double-clicking it, remove the connecting arrow from the address target field, and remove the source fields by choosing Delete Floating Objects on the left-hand side of the data flow editor.

BIT460


Instead of your user-defined function copyPerValue, use the standard function useOneAsMany for the Name target-field mapping. a)

Delete the mapping for the Name target field.


b)

Select the source fields. Drag the Name source field to the data flow editor and drag the Material source field twice by using drag and drop.

c)

Select a standard function. In the lower screen area of the data flow editor, choose Node Functions. Select useOneAsMany and drag the function to the data flow editor by using drag and drop.

d)

Define the user function. Connect the fields in the data flow editor as follows: name = useOneAsMany(name, Material, Material)

e)

Set the context. Set the context for Material (top field icon) to Order by choosing Context → Order from the context menu.

f)

Save the target-field mapping.

g)

Test the mapping. Choose the Test tab page and use the test case already created to test your change by choosing Start Transformation.

2011


111


Load the Name field into the data flow editor by double-clicking it, remove the connecting arrow from the Address target field, and remove the source fields by choosing Delete Floating Objects.


BIT460



112


2011

BIT460


Exercise 8: Create and Use a Function Library For internal use by CSC only

After completing this exercise, you will be able to: • Create function libraries • Use function library functions in a message mapping

Business Example In your company, you are responsible for mapping and have to process mappings for different scenarios. When doing so, you realize that you sometimes need to use the same user-defined functions in different message mappings.

Task: For the message mapping in this task, you need a copy of the local user-defined function copyPerValue that was defined in the message mapping PurchaseOrderToResultset in the previous exercise. You need to create a function library containing the new global copyPerValue function. You must include your new function library in the message mapping PurchaseOrderToResultset and replace the local user-defined function copyPerValue with the global user-defined function of the same name. 1.

Create a function library. Create function library FL_## in your namespace http://educationsap.com/pi/mapping##.

2.

Create a global function. In your function library FL_## (namespace http://educationsap.com/pi/mapping##), create a global function called copyPerValue that has the same interface, properties, and code as the local function copyPerValue from your PurchaseOrderToResultset message mapping.

3.

Include the new global function in the message mapping. In your PurchaseOrderToResultset message mapping, replace the local user-defined function copyPerValue with the corresponding global function from your function library FL_##.

4.

2011

Test your message mapping PurchaseOrderToResultset.


113


Exercise Objectives


BIT460

Solution 8: Create and Use a Function Library For internal use by CSC only

For the message mapping in this task, you need a copy of the local user-defined function copyPerValue that was defined in the message mapping PurchaseOrderToResultset in the previous exercise. You need to create a function library containing the new global copyPerValue function. You must include your new function library in the message mapping PurchaseOrderToResultset and replace the local user-defined function copyPerValue with the global user-defined function of the same name. 1.

Create a function library. Create function library FL_## in your namespace http://educationsap.com/pi/mapping##. a)

Navigate to your namespace. In Enterprise Services Repository, navigate to your namespace http://educationsap.com/pi/mapping## in SWCV SC_BIT_MAP, 1.0.

b)

Create the function library. In the context menu for your namespace, choose New → Mapping Objects → Function Library and create a new function library entitled FL_##.

c)

Save the function library. Enter a meaningful description and save your function library.

2.

Create a global function.


114


2011


Task:

BIT460


a)

Add a function to the global function library. In your function library FL_##, go to Functions and Java Areas and add another entry to the list by choosing Insert Line Below Selection. Enter the name of the copyPerValue function here.

b)

Name the new global function. In the right-hand screen area, enter the title copyPerValue and a suitable description. Set the Execution Type field to All Values of Context.

c)

Add a parameter to the new global function. Add an additional argument of type String to the existing argument var1 by choosing Insert Line Below Selection and name this var2.

d)

Define the new global function. In your message mapping PurchaseOrderToResultset, navigate to the local function copyPerValue, copy the code, and paste it in the editor area of your global function copyPerValue.

e) 3.

Save your function library.

Include the new global function in the message mapping. In your PurchaseOrderToResultset message mapping, replace the local user-defined function copyPerValue with the corresponding global function from your function library FL_##. a)

Display the list of global function libraries. In your message mapping PurchaseOrderToResultset (namespace http://educationsap.com/pi/mapping##), navigate to the mapping editor and choose Show Used Function Libraries (top left button).

b)

Add the newly created global function library. Switch to change mode and add a new line to the Function Libraries Used area that is currently open by choosing Insert Line Below Selection. Use the input help for the Function Library field to fill the new line with the function library FL_## that you created in the second part of this task.

c)

Include a new (global) function in a target field.


2011


115



In your function library FL_## (namespace http://educationsap.com/pi/mapping##), create a global function called copyPerValue that has the same interface, properties, and code as the local function copyPerValue from your PurchaseOrderToResultset message mapping.


BIT460

Navigate to the target-field mapping for the name target field and replace the local user-defined function copyPerValue with the global function copyPerValue from your function library FL_##. For internal use by CSC only

2. 3. d)

In the Functions field of the mapping editor, select FL_## and double-click copyPerValue so that the global function is displayed in the target-field mapping for the name field. Remove all connections for the local function copyPerValue and connect it to the relevant box of the global function copyPerValue. Delete the floating objects by choosing the relevant pushbutton on the right-hand side of the mapping editor.

Include a new (global) function in a target field. Navigate to the target-field mapping for the Address target field and replace the local user-defined function copyPerValue with the global function copyPerValue from your function library FL_##. 1.

2. 3. e)

In the Functions field of the mapping editor, select FL_## and double-click copyPerValue so that the global function is displayed in the target-field mapping for the Address field. . Remove all connections for the local function copyPerValue and connect it to the relevant box of the global function copyPerValue. Delete the floating objects by choosing the relevant pushbutton on the right-hand side of the mapping editor.

Remove the reference to the unused local function. In the Functions field of the mapping editor, select User-Defined and delete your local function copyPerValue by opening the selection menu for the copyPerValue button and choosing Delete Function.

f) 4.

Test your message mapping PurchaseOrderToResultset. a)

116

Save your message mapping.

Choose the Test tab page and use the test data from the previous exercise to test your message mapping by choosing Start Transformation (bottom left).


2011


1.

BIT460


Exercise 9: Work with Local and Global User-Defined Functions For internal use by CSC only

After completing this exercise, you will be able to: • Create and use local user-defined functions in a message mapping • Include and use global user-defined functions in message mappings

Business Example A specific mapping task requires you to use local and global user-defined functions in graphical mapping.

Task: The source message contains purchase order information. This contains header information and multiple detailed purchase orders. Each of these detailed purchase orders contains a supplier name. Each supplier can have multiple purchase orders, and the exact number of suppliers in the source message is unknown. In addition, the purchase orders are not sorted according to supplier. The target message contains a purchase order for each supplier. Each entry for a supplier is to contain the header information from the source message and the corresponding purchase orders. There are numerous ways to handle this mapping task. The solution described here is just one of these many possibilities. 1.

Create a message mapping with the name OrderToSortedOrder.

2.

Specify the source and target message type.

3.

Determine the number of suppliers; this establishes the required number of target fields Orders. Create a user-defined function with the name getSuppliers with the input parameter supplier (and Execution Type = All Values of Context). This function tests all Supplier source fields and returns each supplier only once.

4.

Assign the header information to each Orders purchase order in the target structure: The global function copyPerValue from the function library FL_## created in the last exercise is to be used later in this step. For this reason, you should include this function library in your message mapping now.

5.

Determine the number of target fields Items for each supplier. Continued on next page

2011


117


Exercise Objectives


BIT460


6.

Assign the purchase order information for each order Orders to each target field item: Create a user-defined function with the name assignSupplier (Execution Type = All Values of Context) with the input parameter supplier. This function is to assign the source fields of the source structure Detail to the corresponding target fields of the target structure Items.

7.

Execute the message mapping for the individual target fields; to complete the mapping program, you need eight graphical mappings. Hint: Use the explicit context change for POCombined for all source fields under the Detail source node (Supplier, ProductID, Quantity, Price), so that all source fields are available in the main context.

8.

118

Test the mapping by using the mapping editor test function. For test purposes, use a header and four details with two different Suppliers.


2011


Create a user-defined function with the name assignItems with the input parameter supplier (and Execution Type=All Values of Context). This function determines the number of purchase orders for a supplier and separates them with a context change. A list of target fields Items is to be created for each supplier.

BIT460


Solution 9: Work with Local and Global User-Defined Functions For internal use by CSC only

The source message contains purchase order information. This contains header information and multiple detailed purchase orders. Each of these detailed purchase orders contains a supplier name. Each supplier can have multiple purchase orders, and the exact number of suppliers in the source message is unknown. In addition, the purchase orders are not sorted according to supplier. The target message contains a purchase order for each supplier. Each entry for a supplier is to contain the header information from the source message and the corresponding purchase orders. There are numerous ways to handle this mapping task. The solution described here is just one of these many possibilities. 1.

2.

Create a message mapping with the name OrderToSortedOrder. a)

In software component version SC_BIT_MAP 1.0 in your namespace http://educationsap.com/pi/mapping##, navigate to the Message Mappings node.

b)

Add a new message mapping by displaying the context menu and choosing New.... Enter the name OrderToSortedOrder and your namespace.

c)

Choose Create and enter a description.

Specify the source and target message type. a)

Use POCombined as the source message type. Drag message type POCombined from SWCV SC_BIT_BASE_COMP, 1.0 to the Enter a Source Message area using drag and drop.

b)

Use POSplit as the target message type. Drag message type POSplit from SWCV SC_BIT_BASE_COMP, 1.0 to the Enter a Target Message area using drag and drop.

3.

Determine the number of suppliers; this establishes the required number of target fields Orders.


2011


119


Task:


BIT460

Create a user-defined function with the name getSuppliers with the input parameter supplier (and Execution Type = All Values of Context). This function tests all Supplier source fields and returns each supplier only once. For internal use by CSC only

Create a user-defined function: 1. 2. 3.

4. b)

Select the relevant icon beside Functions in the lower toolbar of the data flow editor. Select getSuppliers as the name and title, fill the Description field. Set the Execution Type field to All Values of Context, and change the name of argument var1 to supplier (in the Signature Variables area). Choose Create Function to create the new function.

Define the mapping function. To define the mapping function, enter the following source code: /* Use vector to test values and save them once in vector */ Vector v = new Vector(); for (int i=0; i
c) 4.

Save the function; choose Close.

Assign the header information to each Orders purchase order in the target structure:


120


2011


a)

BIT460


The global function copyPerValue from the function library FL_## created in the last exercise is to be used later in this step. For this reason, you should include this function library in your message mapping now. For internal use by CSC only

List the currently used function libraries. Choose Show Used Function Libraries (top left pushbutton in the mapping editor) and insert a new line in the Function Libraries Used area that is currently open by choosing Insert Line Below Selection.

b)

Insert the new function library. Use the input help for the Function Library field to fill the new line with the function library FL_## that you created in the last exercise.

5.

Determine the number of target fields Items for each supplier.


2011


121


a)


BIT460


a)

Create a user-defined function: Select the relevant icon beside Functions in the lower toolbar of the data flow editor. Select assignItems as the name and title, fill the Description field, set the Execution Type field to All Values of Context, and change the name of argument var1 to supplier (in the Signature Variables area). Choose Create Function to create the function.

1. 2.

3. b)

Define the new function To define the new function, enter the following source code: /* Use vector to test values and save them once in vector. */ Vector v = new Vector(); for (int i=0; i
c) 6.


Assign the purchase order information for each order Orders to each target field item: Continued on next page

122


2011


Create a user-defined function with the name assignItems with the input parameter supplier (and Execution Type=All Values of Context). This function determines the number of purchase orders for a supplier and separates them with a context change. A list of target fields Items is to be created for each supplier.

BIT460


a)

Create a user-defined function: Select the relevant icon beside Functions in the lower toolbar of the data-flow editor. Choose assignSuppliers as the function name and title, fill the Description field, and set the Execution Type to All Values of Context. Change the name of argument var1 to supplier, and add a second argument with the name detailField (Java type String). Choose Create Function.

1. 2.

3.

4. b)

Define the new function. To define the new user function, enter the following source code: /* Use vector to test values and save them once in vector */ Vector v = new Vector(); for (int i=0; i
c)



2011


123



Create a user-defined function with the name assignSupplier (Execution Type = All Values of Context) with the input parameter supplier. This function is to assign the source fields of the source structure Detail to the corresponding target fields of the target structure Items.


7.

BIT460

Execute the message mapping for the individual target fields; to complete the mapping program, you need eight graphical mappings.


a)

Connect the target field Orders and the source field Supplier: 1. 2.

3. 4. b)

Connect the target field Header and the source field Supplier: 1. 2.

3. 4. 5. c)

Drag the target field Orders and the source field Supplier to the data-flow editor by using drag and drop. In the lower part of the data flow editor, choose the User-Defined function category, then the getSuppliers function, and drag this to the data flow editor by using drag and drop. Connect the fields in the data-flow editor as follows: Orders = getSuppliers (Supplier). Make sure that the context for the Supplier field is set to POCombined.

Drag the target field Header and the source field Supplier to the data flow editor by using drag and drop. In the lower part of the data flow editor, choose the User-Defined function category, then the getSuppliers function, and drag this to the data flow editor by using drag and drop. Select the SplitByValue function from the Node Functions area and drag it to the data flow editor by using drag and drop. Connect the fields in the data flow editor as follows: Header = SplitByValue(getSuppliers(Supplier)). Make sure that the context for the Supplier field is set to POCombined.

Connect the target field toCompany and the source field Supplier: 1. 2.

3. 4.

Drag the target field toCompany and the source field Supplier to the data-flow editor by using drag and drop. Choose the getSuppliers function from the User-Defined function category and the SplitByValue function from the Node Functions area and drag them to the data-flow editor by using drag and drop. Connect the fields in the data-flow editor as follows: toCompany = SplitByValue(getSuppliers(Supplier)). Make sure that the context for the Supplier field is set to POCombined. Continued on next page

124


2011


Hint: Use the explicit context change for POCombined for all source fields under the Detail source node (Supplier, ProductID, Quantity, Price), so that all source fields are available in the main context.

BIT460


d)

Connect the target field custName and the source fields Supplier and Name:

2. 3.

4. 5. 6. e)

Connect the target field custAddress and the source fields Supplier and Address: 1. 2. 3.

4. 5. 6. f)

Drag the target field custName and the source fields Supplier and Name to the data-flow editor by using drag and drop. Under the User-Defined function category, select the getSuppliers function and drag it to the data-flow editor by using drag and drop. Under the FL_## function category, select the global function copyPerValue from your function library and drag it to the data-flow editor by using drag and drop. Select the SplitByValue function from the Node Functions area and drag it to the data-flow editor by using drag and drop. Connect the fields in the data-flow editor as follows: CustName = SplitByValue(copyPerValue(getSuppliers(Supplier), Name)). Make sure that the context for the Supplier field is set to POCombined.

Drag the target field custAddress and the source fields Supplier and Address to the data-flow editor by using drag and drop. Under the User-Defined function category, select the getSuppliers function and drag it to the data-flow editor by using drag and drop. Under the FL_## function category, select the global function copyPerValue from your function library and drag it to the data-flow editor by using drag and drop. Select the SplitByValue function from the Node Functions area and drag it to the data-flow editor by using drag and drop. Connect the fields in the data-flow editor as follows: “custAddress = SplitByValue(copyPerValue(getSuppliers(Supplier), Address))”. Make sure that the context for the Supplier field is set to POCombined.

Connect the target field items and the source field Supplier: 1. 2.

3.

Drag the target field items and the source field Supplier to the data-flow editor by using drag and drop. Choose the User-Defined function category at the bottom of the screen, select the assignItems function, and drag this to the data-flow editor by using drag and drop. Connect the fields in the data-flow editor as follows: items = assignItems(Supplier).


2011


125



1.


4.

Make sure that the context for the Supplier field is set to POCombined.

Connect the target field productNo and the source fields Supplier and ProductID. Drag the target field productNo and the source fields Supplier and ProductID to the data-flow editor by using drag and drop.

h)

Specify the functions to use in the message mapping: 1.

2.

3. i)

Choose the assignSuppliers function from the User-Defined function category and the SplitByValue function from the Node Functions area and drag them to the data-flow editor by using drag and drop. Connect the fields in the data-flow editor as follows: productNo = SplitByValue(assignSuppliers(Supplier, ProductID)). Make sure that the context for the Supplier and ProductId fields is set to POCombined.

Connect the target field quantity and the source fields Supplier and Quantity. Drag the target field quantity and the source fields Supplier and Quantity to the data-flow editor by using drag and drop.

j)


2. 3. k)

Choose the assignSuppliers function from the User-Defined function category and the SplitByValue function from the Node Functions area and drag them to the data-flow editor by using drag and drop. Connect the fields in the data-flow editor as follows: quantity = SplitByValue(assignSuppliers(Supplier, Quantity)). Make sure that the context for the Supplier and Quantity fields is set to POCombined.

Connect the target field price and the source fields Supplier and Price. Drag the target field price and the source fields Supplier, and Price to the data-flow editor by using drag and drop.

l)


Choose the assignSuppliers function from the User-Defined function category and the SplitByValue function from the Node Functions area and drag them to the data-flow editor by using drag and drop. Continued on next page

126


2011



g)

BIT460

BIT460


2.

8.

Test the mapping by using the mapping editor test function. For test purposes, use a header and four details with two different Suppliers. a)

Display the Test tab page.

b)

Create a new XML instance by choosing the Generate Instance icon.

c)

To create additional structures, choose Duplicate Subtree in the context menu for the Detail node. Create four structures for Detail.

d)

Enter test values for the fields of the XML instance. In the source document view, you can compare your instance with the POCombined.xml file, or load the file as an XML instance.

e)

Start the mapping program. Choose Execute Mapping. The result should list the purchase orders for OfficeMax and OfficeDepot separately. You can compare your result with the POSplit.xml file.

2011


127



3.

Connect the fields in the data-flow editor as follows: “Price = SplitByValue(assignSuppliers(Supplier, Price))”. Make sure that the context for the Supplier and Price fields is set to POCombined.


BIT460



128


2011

BIT460


Exercise 10: Use variables in user-defined functions For internal use by CSC only

After completing this exercise, you will be able to: • use variables in user-defined functions

Business Example You have to share data between different user-defined functions and need an easy concept for this.

Task: Define an attribute that can be used in all user-defined functions in a message mapping. Increment the value with each call of one of the user-defined functions, and write the value to the trace.

2011

1.

Copy the message mapping OrderToSortedOrder to OrderToSortedOrder_ext.

2.

Define an attribute of type integer named counter.

3.

Extend the existing user-defined functions so that each function call increases the counter and writes the counter value as information to the trace.

4.

Test the message mapping to check the counter values in the trace.


129


Exercise Objectives


BIT460

Solution 10: Use variables in user-defined functions For internal use by CSC only

Define an attribute that can be used in all user-defined functions in a message mapping. Increment the value with each call of one of the user-defined functions, and write the value to the trace. 1.

Copy the message mapping OrderToSortedOrder to OrderToSortedOrder_ext. a)

Select the message mapping OrderToSortedOrder.

b)

Copy the message mapping. Either open the object and choose Message Mapping / Copy Object ..., or use the secondary mouse on the object in the browser section and choose Copy Object ....

c) 2.

Name the new message mapping OrderToSortedOrder_ext and choose Copy.

Define an attribute of type integer named counter. a)

Switch to edit mode in the message mapping.

b)

Select the Functions tab.

c)

Select the Java Area Attributes and Methods.

d)

Add the following line to the Java Area: int counter=0;

e)


f)

Check the message mapping: choose F7.


130


2011


Task:

BIT460


Extend the existing user-defined functions so that each function call increases the counter and writes the counter value as information to the trace. a)

Select the function getSuppliers to see the source code.

b)

Increase the counter and write information to the trace. Scroll down in the source code and add the following lines on the bottom: ++counter; AbstractTrace trace = container.getTrace(); trace.addInfo(counter + ". call (getSuppliers)");

c)

Repeat steps a) and b) for the other user-defined functions. Open the functions assignItems, and assignSupplier (one after another). Enter the similar source code as above, just replace the name of the function in bracket getSuppliers) with the respective function name.

4.

d)


e)

Check the message mapping: choose F7.

Test the message mapping to check the counter values in the trace. a)

Select the Test tab.

b)

Use the existing test data from the copied message mapping OrderToSortedOrder

c)

Ensure that the Trace Level is set to Info (at minimum).

d)

Execute the test by choosing the Start the Transformationicon at the bottom of the screen on the left. The number of entries in the trace depends on your test data.

2011


131



3.


BIT460

Lesson Summary


132



You should now be able to: • Create user-defined functions and use them in the mapping editor • Define and use both local and global user-defined functions • Create function libraries and include them in a message mapping • Change queues and contexts using standard and user-defined functions • Work with mapping objects • Output messages in the trace log

2011

BIT460

Unit Summary

Unit Summary


2011



You should now be able to: • Create a message mapping that makes use of contexts • Set and delete the message-mapping context • Use advanced options to help debug the message-mapping process • Create user-defined functions and use them in the mapping editor • Define and use both local and global user-defined functions • Create function libraries and include them in a message mapping • Change queues and contexts using standard and user-defined functions • Work with mapping objects • Output messages in the trace log

133

Unit Summary

BIT460



134


2011






Advanced Functions Unit Overview Unit Objectives After completing this unit, you will be able to: • • • • • • •

Define parameters for a mapping program Assign parameters to a mapping program at configuration time Use the term value mapping and therefore make use of advanced message-mapping options Map multiple source and target messages Describe the procedure to use a multi-mapping in an interface determination Create mapping templates Use mapping templates in message mappings

Unit Contents Lesson: Using Parameters in Mapping Programs ..........................136 Exercise 11: Create and Use Parameters in a Message Mapping...141 Lesson: Working with Value Mapping functions ............................147 Exercise 12: Use Value Mapping in a message mapping.............157 Exercise 13: Use RFC Lookup function .................................165 Lesson: Mapping Multiple Messages ........................................173 Lesson: Creating a Message-Mapping Template...........................178 Exercise 14: Create and Use a Mapping Template ....................181

2011


135


Unit 4

Unit 4: Advanced Functions

BIT460

Lesson: Using Parameters in Mapping Programs Lesson Overview For internal use by CSC only


Define parameters for a mapping program Assign parameters to a mapping program at configuration time

Business Example You have to define a graphical RFC lookup in a message mapping. So you need to know how to define parameters in a message mapping, bind the message mapping parameters to the operation mapping parameters, and set up the relevant communication channel in the interface determination.

Message-Mapping Parameters You can use parameters in mapping programs (for example, message mappings and operation mappings). Using parameters in mapping programs means that you do not have to specify values to be used in the mapping until configuration time. Using parameters in a mapping program also improves reusability by enabling the mapping program to be used in different operation mappings with different parameter values. In the mapping program, you define an interface that you can use to copy values to (and query values from) the functions of a mapping program. The values may be payload information transferred to the containers of an integration process. You can use parameters to transfer the following values: •

Simple parameter values: Simple values such as a separator for a concatenation function

•

Dynamic parameter values: Adapters for lookup functions to a mapping program.

136


2011


This lesson explains how to assign parameters to mapping programs at configuration time so that you can enable more applications to be used in a mapping program.

Lesson: Using Parameters in Mapping Programs

Figure 41: Process for Parameterizing Mapping Programs

After you have defined parameters for your mapping program (MMP_1 and MMP_2 in figure above), the mapping program is referenced in an operation mapping. In the operation mapping, you also have to define relevant parameters (OMP_1 and OMP_2 in the figure above) that you connect to the mapping-program parameters using a binding. You must also set up a communication channel by entering the operation mapping in an interface determination, for example, in the Integration Directory. In the interface determination, you assign values to the operation mapping parameters, which are then transferred to the mapping program at runtime. You can use parameters in the following mapping programs: • • •

Message Mappings Java Mapping XSLT Mapping Note: Parameterized Mapping Programs cannot be used on the AEX because it is not possible to specify parameters for the mapping program in a Integrated Configuration, and an Interface Determination cannot be used on AEX.

2011


137



BIT460


BIT460

The Parameter-Definition Process


1. 2. 3.

Define parameters in the message mapping Define parameters in the operation mapping and bind them to the message-mapping parameters Set the mapping parameters in the interface determination

Figure 42: Defining and Using Parameters in the Message Mapping

The parameters are defined on the Signature tab page of the message mapping. Here, you name your parameters, specify whether they are simple type parameters or adapters, and type the parameters. Once you have defined your parameters, you can use them in your target-field mappings in the mapping editor. In the example, the parameter MMP_Delimiter specifies the separator for the standard function concat. Hint: Parameters defined in the Signature are always import parameters. (You can only transfer values of export parameters to integration processes or monitoring processes).

138


2011


The following figures illustrate the implementation of parameters in a message-mapping using the example of a message mapping to which a separator for a concatenation function is to be transferred. The process involves the following high-level steps:


Figure 43: Defining Parameters in the Operation Mapping and Binding

In the operation mapping in which the parameterized message mapping is referenced, you can use the Definition tab page to create parameters. To access the maintenance interface for operation mapping parameters, choose Parameters.... Using a binding, you can connect the operation mapping parameters to the corresponding message mapping parameters.

2011


139



BIT460

BIT460

Figure 44: Setting the Mapping Parameters in the Interface Determination

At the end of the parameter-definition process, you have to enter values for the mapping parameters, for example, in an interface determination in the Integration Directory in which the operation mapping is used. Hint: If the parameters are not displayed in the lower screen area of the interface determination for a parameterized operation mapping, double-click the name of the operation mapping. The parameters are then displayed.

140


2011




BIT460


Exercise 11: Create and Use Parameters in a Message Mapping For internal use by CSC only

After completing this exercise, you will be able to: • Create parameterized message mappings • Execute binding for parameterized message mappings • Assign values to the message-mapping interface in the Integration Directory

Business Example You want to use an existing message mapping in a different context. However, this context requires different values to be set for certain constants. For this reason, you decide to use parameters in the message mapping so that you can set the relevant constants in the Integration Directory according to the context.

Task: You need to define a parameter for the existing message mapping MM_CustomerNameMerge in your namespace http://educationsap.com/pi/mapping## to control which separator is set between the first and last names in the standard function concat. 1.

Open your message mapping. In Enterprise Services Repository, navigate to your namespace http://educationsap.com/pi/mapping## in software component version SC_BIT_MAP, 1.0. Open your message mapping MM_CustomerNameMerge.

2.

Create a message-mapping parameter. Define an import parameter entitled MMP_Delimiter of type string. The parameter should be of a simple type.

3.

Define the operation-mapping parameter. Display the operation mapping OM_CustomerInfoMap and create an import parameter entitled OMP_Delimiter of type string. The parameter should be of a simple type. Then bind the message mapping parameter to the operation mapping parameter you just created.

4.

Activate the interface-determination object. Switch to the Integration Directory and choose your interface determination object BC_CI_Requestor_## | CustomerInformation_Request | |Training. Leave the parameter of the operation mapping OMP_Delimiter blank. Activate your interface determination object.

5.

2011

Start the HTTP client and send a suitable request.


141


Exercise Objectives


BIT460

Solution 11: Create and Use Parameters in a Message Mapping For internal use by CSC only

You need to define a parameter for the existing message mapping MM_CustomerNameMerge in your namespace http://educationsap.com/pi/mapping## to control which separator is set between the first and last names in the standard function concat. 1.

Open your message mapping. In Enterprise Services Repository, navigate to your namespace http://educationsap.com/pi/mapping## in software component version SC_BIT_MAP, 1.0. Open your message mapping MM_CustomerNameMerge. a)

Logon to Enterprise Services Repository.

b)

Open software component version node SC_BIT_MAP 1.0.

c)

Navigate to your namespace. Expand the namespace http://educationsap.com/pi/mapping##.

d)

Open your message mapping. Open the Message Mappings node and double-click MM_CustomerNameMerge

2.

Create a message-mapping parameter.


142


2011


Task:

BIT460


Define an import parameter entitled MMP_Delimiter of type string. The parameter should be of a simple type. a)

Specify the parameter properties.


Name: MMP_Delimiter Category: Simple Type Type: xsd:string Parameter: Import b)

Include the newly created parameter in the message mapping. 1. 2. 3.

c) 3.

Open the mapping editor by choosing the Definition tab page. Double-click the standard function concat in the target-field mapping for the MtName field. In the dialog box that appears containing the separator options available, use the input help to select the MMP_Delimiter parameter you just created.

Save your message mapping.

Define the operation-mapping parameter.


2011


143


Switch to edit mode and choose the Signature tab page. Enter the following field values in the Parameters area:


BIT460

a)

Open the operation mapping. Go to the Operation Mappings node and double-click OM_CustomerInfoMap.

b)

Specify the parameter properties. Switch to change mode. In the Source Operation area, choose Parameters.... Enter the following values in the specified fields: Name: OMP_Delimiter Category: Simple Type Type: xsd:string Parameter: Import Then close the dialog box by choosing OK.

c)

Bind the operation-mapping parameter. Choose the pushbutton located in the Binding field in the Mapping Program area. In the dialog box that opens, use the input help to enter the operation mapping parameter OMP_DelimiterBinding in the Binding field. Then close the popup by choosing Copy Object.

d) 4.

Save your operation mapping and activate both modified mapping objects.

Activate the interface-determination object.


144


2011



Display the operation mapping OM_CustomerInfoMap and create an import parameter entitled OMP_Delimiter of type string. The parameter should be of a simple type. Then bind the message mapping parameter to the operation mapping parameter you just created.

BIT460


a)

Call the Integration Directory. Go to the Process Integration Tools page and call the Integration Directory by clicking Integration Builder link.

b)

Edit your interface-determination object. Open your interface-determination object BC_CI_Requestor_## | CustomerInformation_Request | Training and switch to change mode.

c)

Define the operation-mapping parameter. The operation mapping parameter OMP_Delimiter is displayed at the bottom of the screen (if it is not displayed, double-click the name of the operation mapping). Leave the Value field blank by opening the field help, clicking a constant, and selecting the blank entry.

d) 5.

Save and activate your interface determination.

Start the HTTP client and send a suitable request. a)

Start the HTTP client. Starting the HTTP client simulates an application that generates an XML document and then sends it to the SAP PI pipeline by using the HTTP adapter. Set the details for the parameters so that they match those for your scenario configuration (group number ##).

b)

Send the request To transfer the document to the pipeline, choose Send.

c)

Check the status of the message. Call transaction SXI_MONITOR on the Integration Server (client 800) and check the processing of your messages in the message monitor. The composite name on the output page of the request message should be separated using a blank.

2011


145



Switch to the Integration Directory and choose your interface determination object BC_CI_Requestor_## | CustomerInformation_Request | |Training. Leave the parameter of the operation mapping OMP_Delimiter blank. Activate your interface determination object.


BIT460

Lesson Summary


146



You should now be able to: • Define parameters for a mapping program • Assign parameters to a mapping program at configuration time

2011

BIT460

Lesson: Working with Value Mapping functions

Lesson: Working with Value Mapping functions For internal use by CSC only

This lesson introduces the standard functions for value mapping.

Lesson Objectives After completing this lesson, you will be able to: •

Use the term value mapping and therefore make use of advanced message-mapping options

Business Example You are responsible for the development of mappings in SAP NetWeaver Process Integration and require an overview of the advanced message-mapping options that value mappings provide.

Value Mapping as an Advanced Message-Mapping Option In some situations, senders and receivers know the same objects, but under different names. This value transformation needs to be represented by a mapping program. A simple solution is to use Boolean functions, but this can become too complex. A more elegant way of solving this task is to use value mappings or value-mapping tables. In this case, the values you need to map are stored in a value-mapping table and then read during the mapping. FixValues Value-mapping tables are maintained in the ES Repository Value mapping Value-mapping tables are maintained in the Integration Directory Mapping lookups Value-mapping tables are maintained in a back-end system The standard function FixValues contains fixed value pairs in Enterprise Services Repository, while the standard function Value mapping references value pairs from the configuration. The mapping lookup accesses another system to request the required values for the value mapping. This is explained in more detail in the remainder of the lesson.

2011


147


Lesson Overview


BIT460

Value Mapping with Standard Function FixValues


Figure 45: Value Mapping with the FixValues Standard Function

In the example, the source field CUSTTYPE is mapped to the target field CUSTTYPE. The default value for the target field is “business”. However, if the source field contains the values “B”, then the target field is given the value “business_XX”. In a similar way, a source value “P” will be mapped to target value “private_XX” . Advantages and disadvantages of the standard function FixValues: + Easy to use + Possible to changes entries manually + Good runtime performance - No mass upload of values - Configuration values are in design - Values only used in respective message mapping

Standard Function Value Mapping Due to dependencies on customer-specific data, the actual values in a mapping are often not known until configuration time. For this reason, the standard function Value mapping gives you the option of referencing value-mapping tables, which are saved in the Integration Directory.

148


2011


The following figure shows how the standard function FixValues is used. FixValues is a standard function of the Conversions function group; it enables fixed value pairs to be saved in a message mapping (that is, in Enterprise Services Repository).

BIT460


Enterprise Services Repository: Using Value Mapping in Message Mapping


The following figure shows the required parameters for this function. The entries in the value-mapping table must be assigned to a value-mapping context. This context enables you to distinguish between value mappings from different areas. Hint: Values that are manually maintained in the Integration Directory automatically belong to the context http://sap.com/xi/XI. Alternatively, you can replicate values from outside PI into PI with another context by using an interface (see below). The actual values are referenced with the key fields Agency and Scheme. These key fields must be reused in the configuration.

Figure 46: Value Mapping Using the Standard Function Value Mapping

You can enter any strings for Agency and Scheme for the sender and receiver. It is also possible to save a placeholder for the Agency field for the runtime constant SenderParty or SenderService (and likewise for the receiver), which is replaced by the current value during execution. The standard function Value mapping can be used in different message mappings with the same key fields, thus referencing the same “mapping table”.

2011


149


The standard function Value Mapping is in the Conversions function group area and you insert it between the source and target fields. You do not save the value pairs for the conversion directly as the parameters of the function, but instead specify key fields for accessing the value pairs (conversion values). The value pairs themselves are saved in the configuration (in the Integration Directory), using identical key fields (see below).


BIT460

Integration Directory: Populating a Value Mapping with Values


Figure 47: Value-Mapping Groups in the Integration Directory

A value-mapping group is an object (or instance) that is given different names in different systems. The mapping values in the value-mapping group have no direction: A value-mapping group can be used in a message mapping with Value mapping to generate the value “business_XX” from value “B”, and in another message mapping to convert “business_XX” to “B”. You can also include further values with other agency-scheme values if these represent the same object from a business perspective. Values that are to be converted to one another must be in the same value-mapping group.

150


2011


You create the value mapping tables in the Integration Directory. These values are only valid for the context http://sap.com/xi/XI. Value-mapping groups are created for semantically identical trios of values Agency, Scheme, and Value. The figure Value-Mapping Groups in the Integration Directory shows an example with the semantically identical values “B” and “business_xx”.

BIT460


Hint: To create a value-mapping group directly, in the Integration Directory main menu, choose Object → New, and under Configuration Objects, select the object type Value Mapping Group. Value-mapping groups entered manually in the Integration Directory have the advantage of being able to be versioned and transported (from the DEV to the TEST system, for example). Hint: If the mapping of the standard function Value mapping was not executed, the message trace of the converted message contains the following entry: Key mapping from ... has not been performed. Check the key fields Agency and Scheme.

Figure 48: Value Mapping Overview

Advantages and disadvantages of the standard function Value Mapping: + Possible to change entries manually (not in replication, see below) + Good runtime performance + Configuration values are in the Integration Directory

2011


151



To create conversion values in the Integration Directory, choose Tools →Value Mapping. On the next screen, with Value Mapping Agencies selected, enter the agencies and schemes for the sender and receiver as parameters.


BIT460

+ Possible to use values from different message mappings + Possible to use Java and XSLT mappings + Possible to transport values (DEV to TEST) For internal use by CSC only

- Takes time to learn - Mass upload of values only possible using replication (see below)

Populating a Value Mapping with Values by Using a Service Interface To replicate value-mapping data from other applications in the runtime cache (on the Integration Server), you can use service interfaces (“value-mapping replication interfaces”). The interfaces enable you to realize both synchronous and asynchronous replication scenarios. You can also use these interfaces to automatically create value-mapping groups for mass data. The value-mapping replication interfaces are included in the SAP NetWeaver PI shipment and are located in software component version SAP BASIS → SAP BASIS 7.30 in the namespace http://sap.com/xi/XI/System. There are four interfaces in total; two synchronous and two asynchronous, or two outbound and two inbound. The AS Java offers inbound proxies for the inbound service interfaces. The AS ABAP offers outbound proxies for the outbound interfaces in the basis (in the ABAP stack of the Integration Server, as in every ABAP system based on Basis 6.40 and above). Service Interfaces for Value Mapping Replication Name

Mode

Direction

Implementation

ValueMappingReplication

Async.

Inbound

Java

ValueMappingReplicationOut

Async.

Outbound

ABAP

ValueMappingReplicationSynchronous

Sync.

Inbound

Java

Outbound

ABAP

ValueMappingReplicationOutSynchronous Sync.

Hint: The disadvantage of this replication method is that the value-mapping tables cannot be called in the Integration Directory because the original versions of the runtime data are located in the filling application.

152


2011


+ In replication: Possible to use values from the back end

BIT460


Configuration for Value-Mapping Replication The target of the value mapping values is the PI system's Java stack. The prerequisites are: For internal use by CSC only

Create business system for the PI Java stack In SLD (type AS Java), import to Integration Directory

•

Create communication channel (XI receiver) URL points to http://:/MessagingSystem/receive/JPR/XI

•

Register Java inbound proxy See http://:/ProxyServer/

•

Create routing configuration From sender to business system of PI Java stack

The sender can be any system containing values for value mapping. If it is an ABAP system (with proxy runtime), you can use the ABAP outbound interfaces that are already implemented as ABAP proxies to transfer the data. The sender interface can be any other interface containing the required information. You must also create a mapping (from the sender interface to the ValueMappingReplication interface).

Mapping Lookups Mapping lookups access values (tables) in a back-end system during mapping runtime. The lookup can be executed using the standard functions RFC Lookup or JDBC Lookup (see below), or using the lookup API from java coding. Note: The lookup API can be used either in a user-defined function in a message mapping, or in Java or XSLT mappings. The lookup API provides methods for generic access to application systems using the RFC, JDBC, and SOAP adapter. There is also a special API for the JDBC adapter that simplifies access. The Java program transfers a payload stream to the API, which the Adapter Engine uses to send synchronously to the target system (but not a complete PI message with message header). To deliver to the target system, a communication channel must have been set up in the Integration Directory. The response to this synchronous request is received as a stream by the Java program and must be parsed. For more information about these APIs, see the SAP Developer Network at https://www.sdn.sap.com/irj/sdn/javadocs (you will need an SDN user). If the configuration is complete and runtime is active, you can test lookups as part of a mapping program by using the test environment of an operation mapping.

2011


153


•

BIT460

Figure 49: Mapping Lookups

The mapping editor includes standard functions RFC Lookup and JDBC Lookup that you can use to graphically define a mapping lookup using either the RFC adapter or the JDBC adapter. RFC Lookup takes into account the request, response, and fault parts of an imported RFC-Signature. To be able to model the lookup graphically, the structure of the RFC interface must be known. To use this structure in the mapping editor, you have to import the RFC-Signature into Enterprise Services Repository. In the figure below, an RFC lookup is used in a target-field mapping to obtain additional information about the number of available seats on a flight from an SAP system at runtime. Function module Z_BIT_MAP_GET_FREE_SEATS is used for this purpose. This uses the input parameters (aircraft type and number of occupied seats) to return the number of available seats.

154


2011







BIT460

Figure 50: Standard function RFC Lookup in the Mapping Editor

Advantages and disadvantages of mapping lookups: + Configuration values are in the back-end system + Possible to use values from different mappings + Graphical support for RFC and JDBC – Takes time to learn (programming) when the standard graphical functions (RFC and JDBC) are not used – Runtime performance issues

2011


155


BIT460



156


2011

BIT460


Exercise 12: Use Value Mapping in a message mapping For internal use by CSC only

After completing this exercise, you will be able to: • Use the standard function Value Mapping in message mapping • Enter conversion values for the value mapping • Check the value-mapping groups

Business Example Your company uses different values to represent customer types. You want a conversion to take place in the PI mapping you have created. To do this, you use the standard function Value Mapping.

Task 1: (Design) Use Standard Function Value Mapping in Enterprise Services Repository Use the standard function Value Mapping to enable conversion between different representations of the customer type (CUSTTYPE) field. 1.

In your operation mapping OM_CustomerInfoMap, reference a message mapping MM_CustomerInfo as the mapping program for the response and create this message mapping from the operation mapping.

2.

Map all fields with the same name.

3.

For the CUSTTYPE target field, insert the standard function Value Mapping and save the following parameters: Parameters for Standard Function Value Mapping Context

http://sap.com/xi/XI

Agency

SenderService

Scheme

S_CUSTTYPE_##

Agency

ReceiverService

Scheme

CustType_##

Behaviour if Lookup Fails

Use Key


2011


157


Exercise Objectives


BIT460

Task 2: (Configuration) Create Value Mapping Groups in the Integration Directory. Create Value Mapping Groups and enter the conversion values. For internal use by CSC only

Create a Value Mapping Group named VMG_business_customer_##. Maintain the value mapping between value “B” (for Service Training, Scheme S_CUSTTYPE_##) and value “business_customer_##” (for Service BC_CI_Requestor_##, Scheme CustType_##). Hint: To avoid conflicts while editing the value mapping groups, the schema were set group-specific so that every participant can work on group specific objects.

2.

Create a Value Mapping Group named VMG_private_customer_##. Maintain the value mapping between value “P” (for Service Training, Scheme S_CUSTTYPE_##) and value “private_customer_##” (for Service BC_CI_Requestor_##, Scheme CustType_##).

Task 3: (Optional Monitoring) Check Value-Mapping Groups in Cache Monitoring in the Runtime Workbench Check the value-mapping groups in cache monitoring in the Runtime Workbench. 1.

Navigate to the Cache Monitoring of the value-mapping groups in the Runtime Workbench.

2.

Display the value-mapping for your sender system BC_CI_Requestor_##.

Task 4: (Runtime) Check Execution of the Value Mapping Using a Test Message Use a test message to check whether the Value Mapping is executed. 1.

158

Start the HTTP client and send a suitable request. Check the field content for the CUSTTYPE field in the response.


2011


1.

BIT460


Solution 12: Use Value Mapping in a message mapping For internal use by CSC only

Use the standard function Value Mapping to enable conversion between different representations of the customer type (CUSTTYPE) field. 1.

In your operation mapping OM_CustomerInfoMap, reference a message mapping MM_CustomerInfo as the mapping program for the response and create this message mapping from the operation mapping. a)

Open the operation mapping. In the objects for your namespace http://educationsap.com/pi/mapping##, navigate to the Operation Mappings node and double-click the operation mapping OM_CustomerInfoMap to open it.

b)

Reference message mapping for response. Switch to change mode, select the Response tab page and enter the name MM_CustomerInfo and namespace http://educationsap.com/pi/mapping## as the mapping program (of type Message Mapping).

c)

Create message mapping for response. To create the message mapping, try to open the object by double-clicking the name MM_CustomerInfo (or, in the context menu, choose Subobject → New). Answer the question “Do you want to create the object MM_CustomerInfo?” with Create and confirm again on the following screen by choosing Create.

2.

Map all fields with the same name. a)

Select both root structures. In both structures, select the root structure MtCustomerInfo.

b)

Apply auto-field mapping. Use the function “Map Selected Fields and Substructures if Names Are Identical” (second pushbutton from the left at the top of “Design” tab page) to map all fields.

3.

For the CUSTTYPE target field, insert the standard function Value Mapping and save the following parameters:


2011


159


Task 1: (Design) Use Standard Function Value Mapping in Enterprise Services Repository


BIT460

Context

http://sap.com/xi/XI

Agency

SenderService

Scheme

S_CUSTTYPE_##

Agency

ReceiverService

Scheme

CustType_##

Behaviour if Lookup Fails

Use Key

a)

Open the mapping for CUSTTYPE. To see the mapping so far in the data-flow editor, double-click the CUSTTYPE target field.

b)

Remove the existing mapping. Remove the arrow from the CUSTTYPE target field.

c)

Add the Value Mapping standard function. In the Functions area in the footer of the data-flow editor, select the Conversions category and use drag and drop to drag the Value Mapping function into the data-flow editor.

d)

Connect source and target fields to the Value Mapping. Connect the outbound field of the CUSTTYPE source field with the inbound field of the Value Mapping standard function. Connect the outbound field of the Value Mapping standard function with the inbound field of the CUSTTYPE source field.

e)

Maintain the parameters for the Value mapping. Double-click the Value mapping standard function and maintain the values as listed in the table above. Choose OK to close the window.

f)

Save and activate all objects.


160


2011



Parameters for Standard Function Value Mapping

BIT460


Task 2: (Configuration) Create Value Mapping Groups in the Integration Directory. Create Value Mapping Groups and enter the conversion values. For internal use by CSC only

Create a Value Mapping Group named VMG_business_customer_##. Maintain the value mapping between value “B” (for Service Training, Scheme S_CUSTTYPE_##) and value “business_customer_##” (for Service BC_CI_Requestor_##, Scheme CustType_##). Hint: To avoid conflicts while editing the value mapping groups, the schema were set group-specific so that every participant can work on group specific objects. a)

Create a new Value Mapping Group. In the Integration Directory, choose Object -> New -> Configuration Objects -> Value Mapping Group. Specify the name as VMG_business_customer_## and choose Create to create the group.

b)

Enter the values as given in the table: Value-Mapping-Group VMG_business_customer_## Agency

Scheme

Value

BC_CI_Requestor_##

CustType_##

business_##

Training

S_CUSTTYPE_##

B

Hint: For the Agency, you may use the drop-down menu to select Business System and then select the system from the list of available systems. c)

Save the value mapping group.


2011


161


1.


Create a Value Mapping Group named VMG_private_customer_##. Maintain the value mapping between value “P” (for Service Training, Scheme S_CUSTTYPE_##) and value “private_customer_##” (for Service BC_CI_Requestor_##, Scheme CustType_##). a)

Create a new Value Mapping Group. In the Integration Directory, choose Object -> New -> Configuration Objects -> Value Mapping Group. Specify the name as VMG_private_customer_## and choose Create to create the group.

b)

Enter the values as given in the table: Value-Mapping-Group VMG_private_customer_## Agency

Scheme

Value

BC_CI_Requestor_##

CustType_##

private_##

Training

S_CUSTTYPE_##

P

Hint: Since the values for the Schema are the same as for the first value mapping group, you may now use the input help for Scheme for the values to be listed . c)

Save and activate both value mapping groups.

Task 3: (Optional Monitoring) Check Value-Mapping Groups in Cache Monitoring in the Runtime Workbench Check the value-mapping groups in cache monitoring in the Runtime Workbench. 1.

Navigate to the Cache Monitoring of the value-mapping groups in the Runtime Workbench. a)

Open the Runtime Workbench. You can call the Runtime Workbench from the Process Integration Tools page, for example. Alternatively, you can use the URL http://:/rwb.

b)

Choose Cache Monitoring.

c)

Select Cache Instance Mapping Runtime Cache (Central Adapter Engine).

d)

Select Cache Object value-mapping groups.


162


2011



2.

BIT460

BIT460


Display the value-mapping for your sender system BC_CI_Requestor_##. a)

Leave the context as http://sap.com/xi/XI and use the button Input Help for Agency to select your sender system BC_CI_Requestor_##.

b)

Choose Search for a list of the value-mappings. Hint: The name of the value-mapping group is not displayed.

Task 4: (Runtime) Check Execution of the Value Mapping Using a Test Message Use a test message to check whether the Value Mapping is executed. 1.

Start the HTTP client and send a suitable request. Check the field content for the CUSTTYPE field in the response. a)

Start the HTTP client. Open the HTTP client from the file share. Your instructor will tell you where to find the file. Set the details for the parameters so that they match those for your scenario configuration (group number ##).

2011

b)

To transfer the document to the pipeline, choose Send.

c)

Check in the form in the last text area at the bottom of the response whether the conversion for the CUSTTYPE field has been executed.


163



2.


BIT460



164


2011

BIT460


Exercise 13: Use RFC Lookup function Exercise Objectives For internal use by CSC only

Business Example In a message mapping, you want to use a value-mapping-table located in an ABAP back-end system.

Task 1: Use RFC Lookup standard function in a message mapping Use the standard function RFC Lookup in your message mapping MM_CustomerInfo to call the remote-enabled function module Z_RFM_DEMO_RFC_LOOKUP in Business System Training for the mapping of the source and target field CUSTTYPE. 1.

Open your message mapping MM_CustomerInfo in edit mode.

2.

Maintain a parameter named MMP_RFC_CC of category Adapter and type RFC (Parameter import) for the message mapping.

3.

Add the standard function RFC Lookup to the target field mapping of CUSTTYPE.

4.

Maintain the attributes for the RFC Lookup.

5.

Save and test the message mapping.

Task 2: Use binding in Operation Mapping for parameter of type Adapter Modify your operation mapping OM_CustomerInfoMap to use the modified message mapping MM_CustomerInfo with the parameter and maintain a value for that parameter in the interface determination. 1.

Open your operation mapping OM_CustomerInfoMap in edit mode.

2.

Add a parameter named OMP_CC of type Adapter RFC

3.

Bind that parameter OMP_CC to the parameter of the message mapping MM_CustomerInfo.

4.

Save and activate the operation mapping as well as the message mapping.


2011


165


After completing this exercise, you will be able to: • use RFC lookup standard function in a message mapping • configure a scenario to use an adapter for the RFC lookup

BIT460

5.

Set the name for the communication channel to Training_RFC_In for the interface determination BC_CI_Requestor_## | CustomerInformation_Request | | Training.

6.

Save and activate the interface determination BC_CI_Requestor_## | CustomerInformation_Request | | Training.




Task 3: Test scenario using RFC lookup Test your scenario with the HTTP client to check if the RFC lookup executes.

166

1.

Open the HTTP client.

2.

Send a request.

3.

Check the response.


2011

BIT460


Solution 13: Use RFC Lookup function For internal use by CSC only

Use the standard function RFC Lookup in your message mapping MM_CustomerInfo to call the remote-enabled function module Z_RFM_DEMO_RFC_LOOKUP in Business System Training for the mapping of the source and target field CUSTTYPE. 1.

2.

Open your message mapping MM_CustomerInfo in edit mode. a)

Open SWCV SC_BIT_MAP 1.0, therein your namespace http://educationsap.com/pi/mapping##, and open the node Message Mappings.

b)

Open your message mapping MM_CustomerInfo with a double-click.

c)

Switch to edit mode.

Maintain a parameter named MMP_RFC_CC of category Adapter and type RFC (Parameter import) for the message mapping. a)

Open the Signature tab.

b)

Maintain a parameter named MMP_RFC_CC. In the section Parameters below, in the existing line, click in the field Name and enter MMP_RFC_CC.

c)

Click enter: the other fields are filled.

d)

Change the Category to Adapter. Change the Category from Simple Type to Adapter by selecting the Category field and using the drop-down menu.

e)

Set the Type to RFC. Use the input help to choose Adapter Metadata. Select the Name RFC (Software Component Version SAP BASIS 7.30). Click Apply to close the popup.

f)

Keep the Parameter as Import parameter.


2011


167


Task 1: Use RFC Lookup standard function in a message mapping


Add the standard function RFC Lookup to the target field mapping of CUSTTYPE. a)

Open the Definition tab.

b)

Open the field mapping for the target field CUSTTYPE. Double-click the field CUSTTYPE from the target structure MtCustomerInfo.

c)

Add the standard function RFC Lookup Select the functions category Conversions and drag the function RFC Lookup to the flow editor. Hint: In case the field mapping contains the function Value mapping, delete this Value mapping.

4.

Maintain the attributes for the RFC Lookup. a)

Double-click the function RFC Lookup to open the maintenance view for the parameters.

b)

Maintain the parameter MMP_RFC_CC. In the drop-down menu for Communication Channel, select the parameter MMP_RFC_CC.

c)

Maintain the function module Z_RFM_DEMO_RFC_LOOKUP. Use the input help near the text “Select an RFC module”. In the popup, select the remote-enabled function module (RFM) Z_RFM_DEMO_RFC_LOOKUP. Click Apply to close the popup.

d)

Add the import and the export parameter to the function signature. Open the import and export structure of the RFM by clicking on the little triangles in front of Z_RFM_DEMO_RFC_LOOKUP and Z_RFM_DEMO_RFC_LOOKUP.Response. On the left-hand, select the parameter I_CUST_TYPE and double-click it to add it to the table below. On the right-hand, select the parameter E_CUSTOMER_TYPE and double-click it to add it to the table below.

e)

Close the RFC Lookup maintenance window: Click OK.

f)

Connect the source and target fields CUSTTYPE to the input and output fields of the function RFC Lookup.


168


2011



3.

BIT460

BIT460


Save and test the message mapping. a)


b)

Use the tab Test to navigate to the test section.

c)

Maintain parameters for the payload. Set the value of the CUSTTYPE field to either B or P (in upper case!). Maintain the other fields with arbitrary values.

d)

Specify the communication channel for parameter MMP_RFC_CC. Select the tab Parameters below the input structure. In the parameters section upper part, the Import Parameter MMP_RFC_CC is listed. Use the input help to select the communication channel Training_RFC_In for Communication Component Training. Click Apply to close the Communication Channel selection window.

e)

Execute the test to check if the CUSTTYPE field is converted to lower case. Execute the test by choosing the Start Transformation icon at the bottom of the screen on the left. Check the Result: open the structure MtCustomerInfo to see if the value for the CUSTTYPE field has been converted to lower case. Hint: Do not activate the message mapping now: it is referenced in an operation mapping that does not (yet) supply the name of the communication channel as parameter.

Task 2: Use binding in Operation Mapping for parameter of type Adapter Modify your operation mapping OM_CustomerInfoMap to use the modified message mapping MM_CustomerInfo with the parameter and maintain a value for that parameter in the interface determination. 1.

Open your operation mapping OM_CustomerInfoMap in edit mode. a)

Open the operation mapping. In your namespace http://educationsap.com/pi/mapping##, navigate to the Operation Mappings node and open the operation mapping OM_CustomerInfoMap by double-clicking it.

b)



2011


169



5.


2.

BIT460

Add a parameter named OMP_CC of type Adapter RFC a)

Open the parameters list.


b)

Add a parameter named OMP_CC. In the empty entry field for Name, enter OMP_CC.

c)

Press enter for the other fields to be filled.

d)

Change the Category to Adapter. Change the Category from Simple Type to Adapter by selecting the Category field and using the drop-down menu.

e)

Set the Type to RFC. Use the input help to choose Adapter Metadata. Select the Name RFC (Software Component Version SAP BASIS 7.30). Click Apply to close the popup.

f) 3.

Keep the Parameter as Import parameter.

Bind that parameter OMP_CC to the parameter of the message mapping MM_CustomerInfo. a)

Switch to the Response tab.

b)

Create the binding. In the line for the Mapping Program MM_CustomerInfo, choose the button below Binding. In the popup, select the field with the question mark below Binding to select the parameter OMP_CC. Click OK to close the popup.

4.

Save and activate the operation mapping as well as the message mapping. a)

Save the operation mapping.

b)

Choose the menu option Operation Mapping / Activate.

c)

In the Change list popup, select both the operation mapping as well as the message mapping.

d)

Click Activate to activate the objects.


170


2011


Use the button Parameters for a list of parameters to be displayed below the Request / Response / Fault section.

BIT460


6.

Set the name for the communication channel to Training_RFC_In for the interface determination BC_CI_Requestor_## | CustomerInformation_Request | | Training. a)

Open the Integration Directory.

b)

Open the interface determination BC_CI_Requestor_## | CustomerInformation_Request | | Training.

c)


d)

Click the line with the operation mapping OM_CustomerInfoMap for the parameters to be displayed.

e)

Below, click the question mark below Value and open the input help. Select the communication channel Training_RFC_In for Communication Component Training. Click Apply to close the Communication Channel selection window.

Save and activate the interface determination BC_CI_Requestor_## | CustomerInformation_Request | | Training. a)

Save the interface determination.

b)

Activate the interface determination using the menu Interface Determination / Activate.

Task 3: Test scenario using RFC lookup Test your scenario with the HTTP client to check if the RFC lookup executes. 1.

2.

Open the HTTP client. a)

Open the HTTP client from the file share. Your instructor will tell you where to find the file.

b)

Maintain your group number.

Send a request. a)

3.

Check the response. a)

2011

Transfer the document to the pipeline; choose Send.

Call transaction SXI_MONITOR on the Integration Server (client 800) and check the processing of your messages in the message monitor


171



5.


BIT460

Lesson Summary


172



You should now be able to: • Use the term value mapping and therefore make use of advanced message-mapping options

2011

BIT460

Lesson: Mapping Multiple Messages

Lesson: Mapping Multiple Messages For internal use by CSC only

This lesson explains the concept of multi-mapping by showing how to map multiple source and target messages. The lesson also shows how to reference multi-mapping for the purposes of a receiver determination or an interface determination.


Map multiple source and target messages Describe the procedure to use a multi-mapping in an interface determination

Business Example You are responsible for the development of mappings in SAP NetWeaver Process Integration and need to understand how to use the advanced message mapping options that multi-mapping provide.

Multi-Mapping Configurations Traditionally, mapping programs were used to create 1:1 mappings between source and target messages. However, there are scenarios in which it is necessary to process multiple messages. For example, an integration process (ccBPM) might be designed to wait for multiple messages to arrive before processing all messages and sending them to a receiver. The actual multi-mapping is created in the mapping editor. Hint: Provided the required schemas are available, you can also create a multi-mapping in Java mappings, for example, by exporting the data from Enterprise Services Repository.

2011


173


Lesson Overview


BIT460

The following multi-mapping options are available: •

n:1 mapping:


•

1:n mapping: One large message is split into multiple individual messages (for example, one large purchase order is divided into the individual purchase order items).

•

n:m mapping: n source messages are transformed into m target messages.

The Multi-Mapping Message Structure Multi-mappings reference multiple message structures. All source messages are put in one source structure and all target messages are put in one target structure. For this reason, technically speaking, the mapping program is executed between a source structure and a target structure. The concept of multi-mappings is illustrated in the figure Example of an n:m Multi-Mapping.

Figure 51: Example of an n:m Multi-Mapping

The mapping program creates the values of the target message types Order and OrderInfo from the values of the message types OrderHeader and OrderItem. In this case, only an n:2 multi-mapping is executed. On both sides, the message types

174


2011


Multiple messages are combined into one message (for example, multiple purchase orders are combined to make just single purchase order).

BIT460


are under the root element Messages (the name cannot be changed) and under the elements Message1 and Message2. The sequence is specified by the configuration in the message editor. For internal use by CSC only

Figure 52: Configuration of an n:m Multi-Mapping in the Mapping Editor

Depending on the sequence of the inserted message types in the input field on the Signature tab page, the messages will also be made available in the structure overview on the Definition tab page. In the next step, you define the mapping program in the data flow editor. The following restriction applies for the source and target messages that you reference from a message mapping: The source and target messages can be in a different software component version (SWCV) to the message mapping, but they must both originate from the same SWCV (and, if applicable, underlying SWCV).

Using Multi-Mapping in an Interface Determination You may reference a multi-mapping in an interface determination. The operation mapping used in the interface determination must reference an (1:n) multi-mapping program, which ensures that a single message is split into individual messages in a message split.

2011


175


The figure Configuration of an n:m Multi-Mapping in the Mapping Editor shows the procedure in the mapping editor.


BIT460


Figure 53: Bulk Message in an Interface Determination with multiple receiver interfaces

Both the bulk message and the individual messages have a message header with a receiver interface that is defined by the mapping, and which may be different for each individual message. Hint: For a mapping-based message split, the messages must all be sent by using the same Adapter Engine. Attachments from the original message are not transferred to the messages that are created in the message split. Hint: The AEX (Advanced Adapter Engine Extended) is able to use a mapping-based message split in an interface determination.

176


2011


For example, if the mapping program contains sub structures (or fields) with an occurrence of 0 ... unbounded and one message is to be created for each instance, you can use a multi-mapping to create individual messages. These individual messages are initially bundled into one bulk message. The bulk message is then transferred to the Adapter Engine where it is split up into the individual messages again as illustrated in the following figure.

BIT460


Lesson Summary


2011


177


You should now be able to: • Map multiple source and target messages • Describe the procedure to use a multi-mapping in an interface determination


BIT460

Lesson: Creating a Message-Mapping Template For internal use by CSC only

This lesson shows you how to create a message-mapping template and explains the message-mapping options that a mapping template provides.


Create mapping templates Use mapping templates in message mappings

Business Example You have repetitive mapping tasks that you want to perform with the aid of a single mapping, which you can use as required for multiple substructures.

The Message-Mapping Template In the same way that you reuse data types in different message types, you can also save and reuse parts of message mappings as mapping templates. A mapping template serves as a basic predefined unit that you can load into (and use in) other message mappings and then adjust to meet your requirements. You can create mapping templates for structure mappings for the following types: • • •

Data types Complex types extracted from IDoc structures and RFC function headers Complex types in external definitions Hint: You can also use a mapping template for an individual field provided that the field references a simple data type (and not a XSD data type).

The data types referenced by mapping templates can exist in any software component versions. The following figure illustrates how you can define a mapping template and how you can use existing mapping templates.

178


2011


Lesson Overview

Lesson: Creating a Message-Mapping Template

Figure 54: Using Mapping Templates

In a message mapping, you can display which mapping templates have already been referenced. Furthermore, if structures are selected in the source and target structures, you can also display or create appropriate mapping templates. Hint: A user-defined function is also copied to a mapping template if the user-defined function is used for fields that are part of a structure used for the mapping template. If a mapping template is modified after it has been referenced, the change is not automatically transferred to the message mapping in which the mapping template is referenced.

2011


179



BIT460


BIT460



180


2011

BIT460


Exercise 14: Create and Use a Mapping Template For internal use by CSC only

After completing this exercise, you will be able to: • Create and use mapping templates in a message mapping

Business Example A specific mapping task requires you to use mapping templates in a message mapping.

Task: You want to use a mapping template in a message mapping that maps the message types Contact and Customer. The message type Contact comprises the data types Name and Address; the message type Customer comprises the data types CustName and CustomerAddress. 1.

Start Enterprise Services Repository. Navigate to your namespace http://educationsap.com/pi/mapping## in software component version SC_BIT_MAP, 1.0.

2.

Create a message-mapping template. In your http://educationsap.com/pi/mapping## namespace, create a mapping template with the name NameToCustName. Use the data types Name and CustName (both from SWCV SC_BIT_MAP, 1.0 under Basis Objects in namespace urn:educationsap.com:bit:mapping). Assign the Gender target field to the Title source field. The source fields Firstname and Surname are to be linked with a blank and transferred to the target field Name. Note: To select the source or target structure, select the relevant data type from the navigation tree and link it to the appropriate fields for the structures by using drag and drop.

3.

Test the mapping template.

4.

Create a message mapping with the name ContactToCustomer. In the message mapping, reference the message type Contact as the source structure and the message type Customer as the target structure.

5.


6.

Choose the message-mapping template. Continued on next page

2011


181


Exercise Objectives


BIT460

Select the mapping template NameToCustName as the message-mapping template in the mapping editor between the Name and CustomerName structures. For internal use by CSC only

Connect the address fields in the source and target structures. Connect the fields with the same name in the Address and CustomerAddress structures.

8.

Create another message-mapping template. Create an additional message-mapping template, this time with the name AddressToAddress, between the data types Address and CustomerAddress. An identical mapping is required between the source and target fields Street, ZIPCode, and City.

9.

Save the ContactToCustomer message mapping and display the mapping templates used.

10. Test the mapping by using the mapping editor test function.

182


2011


7.

BIT460


Solution 14: Create and Use a Mapping Template For internal use by CSC only

You want to use a mapping template in a message mapping that maps the message types Contact and Customer. The message type Contact comprises the data types Name and Address; the message type Customer comprises the data types CustName and CustomerAddress. 1.

Start Enterprise Services Repository. Navigate to your namespace http://educationsap.com/pi/mapping## in software component version SC_BIT_MAP, 1.0. a)

Choose the Enterprise Services Builder link from the PI Tools Homepage.

b)

Navigate to your namespace. Expand the software component version SC_BIT_MAP, 1.0 followed by your namespace http://educationsap.com/pi/mapping##.

2.

Create a message-mapping template. In your http://educationsap.com/pi/mapping## namespace, create a mapping template with the name NameToCustName. Use the data types Name and CustName (both from SWCV SC_BIT_MAP, 1.0 under Basis Objects in


2011


183


Task:


BIT460

namespace urn:educationsap.com:bit:mapping). Assign the Gender target field to the Title source field. The source fields Firstname and Surname are to be linked with a blank and transferred to the target field Name. For internal use by CSC only

a)

Create a mapping template. Go to the objects for your namespace http://educationsap.com/pi/mapping##. To create a new mapping template, call the context menu and choose New → Mapping Objects → Mapping Template. Enter the name NameToCustName and choose Create.

b)

Select the source and target data types. 1.

2. 3. c)

Connect source and target fields. 1. 2.

3.

4. d)

In SWCV SC_BIT_MAP, 1.0, choose Basis Objects → urn:educationsap.com:bit:mapping → Interface Objects → Data Types. Using drag and drop, drag the Name data type to the Select a Source Type field. Using drag and drop, drag the CustName data type to the Select a Target Type field.

Drag the Gender target field to the Title source field. Drag the Name target field to the data flow editor, followed by the Firstname and Surname source fields, and finally the concat standard function (from the Text function category). Drag a connecting line from the source field of Firstname to the top-left concat inbound field, and from the source field of Surname to the bottom-left concat inbound field. Drag a connecting line from the source field of concat to the Name inbound field.

Specify the function to use. Choose the concat function and enter a blank as a delimiter to separate the fields.

e)

Save your changes. Choose Apply to leave the screen for maintaining the properties of the concat step.


184


2011


Note: To select the source or target structure, select the relevant data type from the navigation tree and link it to the appropriate fields for the structures by using drag and drop.

BIT460


4.

Test the mapping template. a)

Choose the Test tab page and create a new XML instance by choosing Generate Instance.

b)

Expand the nodes in the XML instance and populate the fields with test values.

c)

Start the mapping-template test by choosing Execute Mapping.

Create a message mapping with the name ContactToCustomer. In the message mapping, reference the message type Contact as the source structure and the message type Customer as the target structure. a)

Create the new message mapping. 1. 2. 3.

b)

Display the objects for your namespace http://educationsap.com/pi/mapping##. To create a new message mapping, choose New → Mapping Objects → Message Mapping in the context menu. Enter the name ContactToCustomer and your namespace and choose Create and enter a description.

Specify the source message type. Using drag and drop, drag the Contact message type to the Select a Source Type field.

c)

Specify the target message type. Using drag and drop, drag the Customer message type to the Select a Target Type field.

5.

6.

Connect source and target fields. a)

Connect the CustID field of the target structure to the Ref field of the source structure.

b)

Drag the CustID field of the target structure to the Ref field of the source structure using drag and drop.

Choose the message-mapping template. Select the mapping template NameToCustName as the message-mapping template in the mapping editor between the Name and CustomerName structures. a)

Select the Name and CustomerName structures.

b)

Either call the context menu for the CustomerName structure and choose Show Suitable Templates, or choose the Show Suitable Templates icon.

c)

Select the message-mapping template NameToCustName. Continued on next page

2011


185



3.


7.

BIT460

Connect the address fields in the source and target structures.

8.

a)

Select the Address and CustomerAddress substructures.

b)

Choose the Assign Selected Fields and Substructures with Same Names icon and confirm the subsequent warning by choosing Continue.

Create another message-mapping template. Create an additional message-mapping template, this time with the name AddressToAddress, between the data types Address and CustomerAddress. An identical mapping is required between the source and target fields Street, ZIPCode, and City.

9.

a)

Select the fields Address and CustomerAddress. Either call the context menu for CustomerAddress and choose Create Template Based on Mapping, or choose the Create Template Based on Mapping icon.

b)

On the subsequent screen, enter the name as AddressToAddress and confirm by choosing Create.

c)

Save the mapping template.

Save the ContactToCustomer message mapping and display the mapping templates used. a)

Save the message-mapping object. Navigate back to the ContactToCustomer message mapping and save the object.

b)

List the message-mapping templates used in the message mapping. Choose the Display Mapping Templates Used icon. Hint: The system displays only one mapping template (NameToCustName); the other mapping template was created from the message mapping but not applied in it.

10. Test the mapping by using the mapping editor test function.

186

a)

Choose the Test tab page and create a new XML instance by choosing Generate Instance.

b)

Expand the nodes in the XML instance and populate the fields with test values.

c)

Execute the mapping by choosing Execute Mapping.


2011



Connect the fields with the same name in the Address and CustomerAddress structures.

BIT460


Lesson Summary


2011



You should now be able to: • Create mapping templates • Use mapping templates in message mappings

187

Unit Summary

BIT460

Unit Summary


188


2011


You should now be able to: • Define parameters for a mapping program • Assign parameters to a mapping program at configuration time • Use the term value mapping and therefore make use of advanced message-mapping options • Map multiple source and target messages • Describe the procedure to use a multi-mapping in an interface determination • Create mapping templates • Use mapping templates in message mappings






Other Mapping Types Unit Overview This course focuses on graphical message mapping. However, it is also relevant to look at other mapping types that can be combined with message mapping.

Unit Objectives After completing this unit, you will be able to: • • •

import and use XSLT mappings explain the main steps to create a Java mapping program Import and use a Java mapping in an Operation Mapping

Unit Contents Lesson: Importing and Using XSLT Mapping ...............................190 Exercise 15: Import and Use XSLT Mappings ..........................195 Lesson: Creating a Java Mapping ............................................200 Exercise 16: Create and Use a Java Mapping .........................205

2011


189


Unit 5

Unit 5: Other Mapping Types

BIT460

Lesson: Importing and Using XSLT Mapping Lesson Overview For internal use by CSC only

Lesson Objectives After completing this lesson, you will be able to: •

import and use XSLT mappings

Business Example You are responsible for the development of mappings in SAP PI and need to know how to integrate XSLT mappings.

XSLT Mapping Within SAP PI You can create XSLT mapping programs either as ABAP-XSL transformations or directly in XSLT. XSLT is a transformation language used to describe transformations of XML files. To transform an XML file, you require the source document, the transformation statements (known as an XSL stylesheet), and an XSLT engine to process the statements. You develop and test the stylesheet externally in an appropriate XSLT editor before importing it into Enterprise Services Repository. • • • • •

Develop the XSLT mapping program (stylesheet) locally. Create an archive (JAR or Zip) for the stylesheet. Create an Imported Archive in Enterprise Services Repository Import the XSLT archive into the Imported Archive. Reference the XSLT mapping program in the operation mapping.

If necessary, you can edit the XSLT file after it has been imported. In the figure Example of an XSLT Mapping, the source field Class is mapped to the target field Class. The value “business” is mapped to the value “2”.

190


2011


This lesson looks at the way XSLT mappings work and how you can use them.

Lesson: Importing and Using XSLT Mapping

Figure 55: Example of an XSLT Mapping

You have the option of using XPath statements in XSLT mappings. Like XSLT, XPath is an XML specification. You can use XPath to address any elements in an XML document. XSLT uses XPath to select substructures in XML documents. The required transformations are executed for these substructures by using templates defined in XSLT. You can use the XSLT tags and to read templates for substructures. In this way, you can break down a large XSLT mapping program into smaller packages, and save them in one or more archives. Furthermore, you can reuse XSLT templates for data types because they can be called in other XSLT mappings. • • • • •

XSLT Mapping: transforms an XML document XPath: localizes substructures in an XML document and allow you to import additional XSLT files enables the runtime constants to be accessed External Java methods can be called in XSLT mappings

Using Java Methods in XSLT In the figure below, the Java method merge is called from an XSLT stylesheet. The call xnlns:javamap=java:com.company.group.MappingClass defines the namespace in which the class (and therefore also the method) is located. The tag
2011


191



BIT460


BIT460

$last)/> executes the call. Javamap selects the namespace defined above, and merge($first, $last) calls the method merge. The result of the method is shown in the resulting file. For internal use by CSC only


Figure 56: Example of an XSLT Mapping Using the Method Merge

Runtime Constants It is possible to use runtime constants that you use to read data that is not known until runtime. Important Runtime Constants

192

Runtime Constant

Meaning

$SenderService

Service at the sender that is to send the message

$ReceiverService

Service at the receiver that is to receive the message

$Direction

Message direction (request, response, and fault)

$Interface

Sender interface name

$InterfaceNamespace

Sender interface namespace

$ReceiverName

Receiver interface name

$ReceiverNamespace

Receiver interface namespace


2011

BIT460




To access a constant in the XSLT program, it must first be declared as a parameter. For example: . Once declared, you can then use the parameter just like any other XSLT parameter.

Accessing Runtime Constants ... ...

Trace Messages To define warnings (that either cause processing to terminate or allow it to continue), use the XSLT statement .

Syntax and Example for the Statement // Example: This is a warning!

The XSLT statements in the following example test the current source value of the test tag and set a corresponding target value. If neither of the two expected values are found, the result is displayed as a warning, for example: Mr. Mrs. Mr. or Mrs. Gender had neither 0 nor 1! "Mr. or Mrs." was set as title.
2011


193


BIT460

SAP XML Toolkit deprecated For PI 7.3 (which is based on JDK 6), the use of the SAP XML Toolkit is deprecated.


Compared to the SAP XML Toolkit, the usage of the JDK has the following advantages: • • •

XSLT programs are executed more quickly Better error handling Supports a wider range of functions than the SAP XML Toolkit

Figure 57: XSLT Mapping - SAP XML Toolkit is deprecated

You will still be able to use the SAP XML Toolkit with PI 7.3. We recommend to test existing XSLT programs and adjust them if necessary. So deselect the option Use SAP XML Toolkit (which refers to the XSLT mapping program) in the operation mapping.

194


2011


Note: Before PI 7.1, XSLT programs were executed using the SAP XML Toolkit. This became obsolete when version 5 of the Java Development Kit (JDK) was introduced with PI 7.1.

BIT460


Exercise 15: Import and Use XSLT Mappings For internal use by CSC only

After completing this exercise, you will be able to: • Import an XSLT mapping program that has been created externally into Enterprise Services Repository • Edit an imported XSLT mapping program • Use an imported XSLT mapping program in an operation mapping

Business Example You want to know the procedure for using an external XSLT mapping in an operation mapping.

Task 1: Import the XSLT mapping NameMerge.xsl for the mapping between the data types MtCustomerName and MtPerson. Check that the mapping does not contain any errors and use it in the operation mapping OM_CustomerInfoMap. 1.

Import the NameMergeXSL.zip archive in Enterprise Services Repository in software component version SC_BIT_MAP 1.0 in your namespace http://educationsap.com/pi/mapping##.

2.

Check that the XSLT mapping and adapt your group number.

3.

Use the XSLT mapping in your operation mapping. Make the necessary changes to your operation mapping OM_CustomerInfoMap so that it uses your imported XSLT mapping NameMerge.xsl.

Task 2: Testing the XSLT Mapping Test the XSLT mapping by starting another call from the HTTP client.

2011

1.

Send a request from the HTTP client.

2.

In the message monitor, check whether the XSLT mapping was used.


195


Exercise Objectives


BIT460

Solution 15: Import and Use XSLT Mappings For internal use by CSC only

Import the XSLT mapping NameMerge.xsl for the mapping between the data types MtCustomerName and MtPerson. Check that the mapping does not contain any errors and use it in the operation mapping OM_CustomerInfoMap. 1.

Import the NameMergeXSL.zip archive in Enterprise Services Repository in software component version SC_BIT_MAP 1.0 in your namespace http://educationsap.com/pi/mapping##. a)

Create new Imported Archive. Expand the software component version node SC_BIT_MAP 1.0 followed by your namespace http://educationsap.com/pi/mapping##. To create a new archive, call the context menu for Imported Archives and choose New → Mapping Objects.

b)

Specify archive parameters. Enter NameMergeXSL as the name of the archive, leave the namespace as http://educationsap.com/pi/mapping##, and choose Create to create a new archive.

c)

Import the XSL Stylesheet. In the detail view for the archive, choose Tools → Import Archive to import the archive NameMergeXSL.zip. The Imported Archive now contains the XSL mapping NameMerge.xsl.

d) 2.

Save the archive.

Check that the XSLT mapping and adapt your group number. a)

Open the XSLT mapping. Ensure you are in edit mode in the archive NameMergeXSL and then choose Edit to open the XSLT mapping in change mode. Go to the source text view.

b)

Check the XSL stylesheet. Check whether the XML document is a XSL stylesheet and which namespaces are used:

196


2011


Task 1:

BIT460


xmlns:ns0="urn:educationsap.com:bit:mapping">

Ensure that you change ## to the number corresponding to your namespace. c)

The declared template NameMerge is to be applied to the source structure element MtCustomerName in the namespace http://educationsap.com/pi/mapping##: ...

d)

The content of the NameMerge template is the merging of the source fields Name and Surname, separated by a blank, and entered in the target field MtName in the namespace urn:educationsap.com:bit:mapping : ...

e)

Activate the Imported Archive. Close the editor window, save, and activate the archive NameMergeXSL.

3.

Use the XSLT mapping in your operation mapping.


2011


197




BIT460

Make the necessary changes to your operation mapping OM_CustomerInfoMap so that it uses your imported XSLT mapping NameMerge.xsl. For internal use by CSC only

Open the operation mapping. In your namespace, navigate in the mapping objects to the operation mappings and open your operation mapping OM_CustomerInfoMap by double-clicking.

b)

Switch to edit mode. First, under Mapping Program in the Request area, use the input help to select the type XSL. Next, enter your new XSLT mapping NameMerge under Name. Ensure that Use SAP XML Toolkit is deselected.

c)

Save and activate the changed operation mapping.

Task 2: Testing the XSLT Mapping Test the XSLT mapping by starting another call from the HTTP client. 1.

Send a request from the HTTP client. a)

Start the HTTP client. Set the details for the sender service so that they match those for your scenario configuration.

b) 2.

Choose Send to transfer the document to the pipeline.

In the message monitor, check whether the XSLT mapping was used. a)

Open the message monitor. Call transaction SXI_MONITOR on the Integration Server. In the Advanced tab, set the Client to 800. Check the processing of your messages in the message monitor.

b)

View the message trace. Navigate to the detail view of your message and open the trace (under SOAP Header → Trace) in the processing step Request Message Mapping in either one of the windows.

c)

198

At the very bottom of the trace area, you can find the message indicating which operation mapping and mapping program were executed.


2011


a)

BIT460


Lesson Summary You should now be able to: • import and use XSLT mappings For internal use by CSC only


2011


199


BIT460

Lesson: Creating a Java Mapping For internal use by CSC only

This lesson looks at the way Java mappings have to be developed, and how you can use them.


explain the main steps to create a Java mapping program Import and use a Java mapping in an Operation Mapping

Business Example You are responsible for the development of mappings in SAP PI and require an overview of the options that are provided by Java mappings.

Steps to create a Java mapping program You have to perform the following steps to use a Java mapping program in an Operation Mapping: •

Develop the Java mapping program in an Development Environment like SAP NetWeaver Developer Studio

•

Create a JAR (or Zip) archive with the compiled Java program as content

•

Create an Imported Archive in Enterprise Services Repository

•

Import the JAR (or Zip) archive file into the Imported Archive

Afterwards, you can reference the Java mapping program in an Operation Mapping using the input help. Note: You cannot edit Java programs in an Imported Archive.

200


2011


Lesson Overview

BIT460

Lesson: Creating a Java Mapping

Implementing a Java mapping program To implement a Java mapping program, proceed as follows:


The Java mapping API provides a framework only, without requiring a specific type of implementation. For example, Java API for XML Processing (JAXP) is available for processing XML documents. Note: JAXP supports the Document Object Model (DOM) and the Simple API for XML (SAX). The implementation is not in the focus of this lesson. The required libraries are shipped with the installation of the AS Java in the archive com.sap.xpi.ib.mapping.lib.jar (to be found in: usr/sap//DVEBMGS/J2EE/cluster/bin/ext/com.sap.xi.mapping.tool.lib/lib). The Java mapping API has been revised and this new API has to be used for new Java mapping programs with PI 7.3. It is documented in SDN: https://www.sdn.sap.com/irj/sdn/javadocs (SDN user required) The following source code shows the main parts.

Java Mapping Template import com.sap.aii.mapping.api.AbstractTransformation; import com.sap.aii.mapping.api.StreamTransformationException; import com.sap.aii.mapping.api.TransformationInput; import com.sap.aii.mapping.api.TransformationOutput; import com.sap.aii.mapping.api.InputHeader; // ... additional imports public class JavaMapping implements AbstractTransformation { } public void transform(TransformationInput in, TransformationOutput out) throws StreamTransformationException { try { // do the mapping, for example using a DOM parser... }}}

Hint: You can export the required XML schemas from Enterprise Services Repository.

2011


201


Create a Java class extending the interface AbstractTransformation. Implement the method transform with the mapping.

• •


BIT460

Accessing Parameters and Header Fields

public void transform(TransformationInput in, TransformationOutput out) throws StreamTransformationException { try { ... // Use method to access parameters for parameterized mapping: String inParam = in.getInputParameters().getString("PARAM_1");

You can access parameters specified in the Operation Mapping using the method getInputParameters() of the in parameter, see coding above. In this example, it is assumed that a parameter named PARAM_1 is specified in the Operation Mapping. You define the Java mapping parameters for a Java mapping program when you create the binding in the operation mapping, and at the same time connect them to operation mapping parameters. When you access the Java mapping parameters in the Java mapping program, the mapping runtime checks whether you have defined the parameters in the operation mapping. If they were not defined, an exception is raised.

Accessing Header Fields public void transform(TransformationInput in, TransformationOutput out) throws StreamTransformationException { try { ... // Use get methods of InputHeader to access Header Fields: InputHeader messageHeader = in.getInputHeader(); String messageId = messageHeader.getMessageId();

You can access header fields of the PI message using the getInputHeader() method of the in parameter and subsequently methods like getMessageId() for the messageId, see coding above.

202


2011



Accessing Parameters

BIT460


Accessing adapter specific message attributes For internal use by CSC only

import com.sap.aii.mapping.api.DynamicConfigurationKey; ... private static final DynamicConfigurationKey DYN_PARA =


import com.sap.aii.mapping.api.DynamicConfiguration;

DynamicConfigurationKey.create("http://sap.com/xi/XI/System/HTTP","UrlParamOne"); public void transform(TransformationInput in, TransformationOutput out) throws StreamTransformationException { try { DynamicConfiguration conf = in.getDynamicConfiguration(); String myParaStr = ""; myParaStr = conf.get(DYN_PARA); getTrace().addInfo(myParaStr); ...

You can access or set adapter specific message attributes with the getDynamicConfiguration() method, see coding above. DynamicConfiguration is a map containing adapter specific message attributes, associating DynamicConfigurationKeys with string values.

Trace Messages You can create entries in the mapping trace using the getTrace method of the class AbstractTransformation:

Working with Trace in Java Mapping public void transform(TransformationInput arg0, TransformationOutput arg1) throws StreamTransformationException { ... getTrace().addInfo("This is an information trace message.");

Note: Similar methods addWarning(String message); and addDebugMessage(String message); can be used.

2011


203


BIT460

Additional notes

• •

204

Not stateful: Java mappings must not be stateful, that is, nothing can be written to the database. If a PI message is resent because of an error, this can lead to database inconsistencies. Value Mapping: An API is available for executing value mappings. The relevant classes are part of the package com.sap.aii.mapping.key.*. Lookup API: you can use an API for a Value Mapping Lookup. You have to import a parameter of type Adapter into your Java mapping (in.getInputParameters().getChannel("CommunicationChannelName"); ). For internal use by CSC only


•


2011

BIT460


Exercise 16: Create and Use a Java Mapping For internal use by CSC only

After completing this exercise, you will be able to: • Create a Java mapping program • Import a Java mapping program that has been created externally into Enterprise Services Repository • Use an imported Java mapping program in an operation mapping

Business Example You want to create a Java mapping program to use it in an operation mapping.

Task 1: Creating and Using a Java Mapping Create and use a Java mapping program 1.

Create a new Java project entitled CustomerInfo in the SAP NetWeaver Developer Studio.

2.

Create a new package com.educationsap.pi.mapping## in the project CustomerInfo.

3.

Import the example solution NameMergeJava.java to your project CustomerInfo to package com.educationsap.pi.mapping##.

4.

Adapt the example solution: change the package name suffix to your group number.

5.

Set the project reference to the library com.sap.xpi.ib.mapping.lib.jar

6.

Compile the class NameMergeJava.java and generate a Java archive NameMerge##.jar from the class file.

7.

Import the NameMergeJava##.jar Java archive in Enterprise Services Repository in software component version SC_BIT_MAP 1.0 in your namespace http://educationsap.com/pi/mapping##.

8.

Reference the java mapping program NameMerge.java in your operation mapping OM_CustomerInfoMap.

Task 2: Testing a Java Mapping Test the Java mapping by starting another call from the HTTP client.

2011

1.

Send a request from the HTTP client.

2.

Check in the message monitor whether the Java mapping was used.


205


Exercise Objectives


BIT460

Solution 16: Create and Use a Java Mapping For internal use by CSC only

Create and use a Java mapping program 1.

Create a new Java project entitled CustomerInfo in the SAP NetWeaver Developer Studio. a)

Start the SAP NetWeaver Developer Studio. To start the SAP NetWeaver Developer Studio, use the shortcut in the archive.

b)

Start the Project creation wizard. Create a new project by choosing File → New → Project. Select the type Java Project.

c)

Specify the project attributes. Choose Next to continue. Give the project the name CustomerInfo, and leave all other settings as default.

d) 2.

Create the project; choose Finish.

Create a new package com.educationsap.pi.mapping## in the project CustomerInfo. a)

Start the package creation. In Package Explorer, select the CustomerInfo project and create a new package by choosing File → New → Package.

b)

Specify the package attributes. Keep the Source Folder as CustomerInfo and enter com.educationsap.pi.mapping## as the name of the package.

c)

Create the package; choose Finish.


206


2011


Task 1: Creating and Using a Java Mapping

BIT460


3.

Import the example solution NameMergeJava.java to your project CustomerInfo to package com.educationsap.pi.mapping##. a)

Start the import wizard.


b)

Open the folder General, select the entry File System, and choose Next.

c)

Set the import folder. Choose Browse to navigate to the directory that contains the Java mapping; choose OK to select that folder.

d)

Import the java file. Select the Java source code NameMergeJava.java from the list of files. Keep the default value for Into Folder and start the import by choosing Finish.

4.

Adapt the example solution: change the package name suffix to your group number. a)

Open the Java file NameMergeJava.java by double-clicking the name.

b)

Correct your group number (##) in the package name (first line). Hint: The com.educationsap.pi.mapping## package corresponds to the http://educationsap.com/pi/mapping## namespace.

c)

The import statement references classes com.sap.aii.mapping.api.* from the library com.sap.xpi.ib.mapping.lib.jar.

d)

In the method transform, the DOM parser is used to parse the XML document.


2011


207


Call the context menu for package com.educationsap.pi.mapping## and choose Import.


5.

BIT460

Set the project reference to the library com.sap.xpi.ib.mapping.lib.jar a)

Open the project properties.

b)

Maintain the Java Build Path. On the menu left-hand, choose Java Build Path. On the right-hand, choose the Libraries tab page

c)

Add external Jar. Use the button Add External Jars to assign the file com.sap.xpi.ib.mapping.lib.jar.

d) 6.

Close the Properties for CustomerInfo window by choosing OK.

Compile the class NameMergeJava.java and generate a Java archive NameMerge##.jar from the class file. a)

SAP NetWeaver Developer Studio automatically compiles when you save the Java class file.

b)

Export the file into a jar file. Call the context menu for package com.educationsap.pi.mapping## and choose Export.

c)

Select Java -> JAR file as the export destination and choose Next.

d)

Set resources to export. In the area Select the resources to export, select the package CustomerInfo / src / com.educationsap.pi.mapping##, and in the right-hand window, select NameMergeJava.java. Keep the selected option Export generated class files and resources (you can only use the compiled class in Java mapping). For the field JAR file, choose Browse to select the directory and specify the name NameMergeJava##.jar as the Export Destination, and keep the selection option Compress the contents of the jar file.

e)

Choose Finish to generate the Java archive NameMergeJava##.jar.


208


2011



Use the Properties context menu for the project CustomerInfo.

BIT460


7.

Import the NameMergeJava##.jar Java archive in Enterprise Services Repository in software component version SC_BIT_MAP 1.0 in your namespace http://educationsap.com/pi/mapping##.


Create a new Imported Archive. To create a new archive, call the context menu for Imported Archives and choose New.... Enter NameMergeJava as the name of the archive, leave the namespace as http://educationsap.com/pi/mapping##, and choose Create to create a new archive.

b)

Import the java archive. In the detail view for the archive, choose Tools → Import Archive to import the Java archive NameMergeJava##.jar. The archive now contains the Java mapping NameMergeJava.class.

c) 8.

Save and activate the archive.

Reference the java mapping program NameMerge.java in your operation mapping OM_CustomerInfoMap. a)

Open operation mapping. In your namespace, navigate in the mapping objects to the operation mappings and open your operation mapping OM_CustomerInfoMap by double-clicking.

b)

Delete the existing mapping program assignment. Switch to edit mode. In the Request section, delete the existing line by selecting the line and using the button Delete Selected Lines.

c)

Reference the java mapping program. Insert a new line. Use the drop-down menu to select the type Java Class. Next, use the input help for the Name field to select your Java mapping NameMerge.

d)

Save and activate the changed operation mapping.


2011


209


a)


BIT460

Task 2: Testing a Java Mapping Test the Java mapping by starting another call from the HTTP client. Send a request from the HTTP client. a)

Open the HTTP client. This simulates an application that generates an XML document and sends it to the SAP PI pipeline by using the HTTP adapter. Set the details for the parameters so that they match those for your scenario configuration (group number ##).

b) 2.

210

Choose Send to transfer the document to the pipeline.

Check in the message monitor whether the Java mapping was used. a)

Call transaction SXI_MONITOR on the Integration Server (client 800) and check the processing of your message in the message monitor.

b)

Navigate to the detail view of your message and open the trace (under SOAP Header → Trace) in the processing step Request Message Mapping in either one of the windows.

c)

At the very bottom of the trace area, you can find the message indicating which operation mapping and mapping program were executed.


2011



1.

BIT460


Lesson Summary


2011



You should now be able to: • explain the main steps to create a Java mapping program • Import and use a Java mapping in an Operation Mapping

211

Unit Summary

BIT460

Unit Summary


212



You should now be able to: • import and use XSLT mappings • explain the main steps to create a Java mapping program • Import and use a Java mapping in an Operation Mapping

2011





BIT460

Course Summary

Course Summary You should now be able to:


2011

Create, test, and use message mappings Use advanced features of mapping types



• •

213

Course Summary

BIT460



214


2011

SAP AG has made every effort in the preparation of this course to ensure the accuracy and completeness of the materials. If you have any corrections or suggestions for improvement, please record them in the appropriate place in the course evaluation.

2011


215



Feedback

Bit460 en Col95 Fv Part a4 Notes(2)

Recommend Documents