How-to Guide

SAP NetWeaver ‘04

How To… Replicate MDM key mapping in XI value mapping tables Version 1.00 – November 2005

Applicable Releases: SAP NetWeaver ’04 MDM 5.5 XI 3.0

© Copyright 2005 SAP AG. All rights reserved.

No part of this publication may be reproduced or

transmitted in any form or for any purpose without the

express permission of SAP AG. The information

contained herein may be changed without prior notice.

Some software products marketed by SAP AG and its

distributors contain proprietary software components of

other software vendors.

Microsoft, Windows, Outlook, and PowerPoint

are

registered trademarks of Microsoft Corporation.

IBM, DB2, DB2 Universal Database, OS/2, Parallel

Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400,

iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent

Miner, WebSphere, Netfinity, Tivoli, and Informix are

trademarks or registered trademarks of IBM Corporation

in the United States and/or other countries.

Oracle is a registered trademark of Oracle Corporation.

UNIX, X/Open, OSF/1, and Motif are registered

trademarks of the Open Group.

Citrix, ICA, Program Neighborhood, MetaFrame,

WinFrame, VideoFrame, and MultiWin are trademarks

or registered trademarks of Citrix Systems, Inc.

HTML, XML, XHTML and W3C are trademarks or

registered trademarks of W3C®, World Wide Web

Consortium, Massachusetts Institute of Technology.

Java is a registered trademark of Sun Microsystems, Inc.

JavaScript is a registered trademark of Sun Microsystems,

Inc., used under license for technology invented and

implemented by Netscape.

MaxDB is a trademark of MySQL AB, Sweden.

SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP

NetWeaver, and other SAP products and services

mentioned herein as well as their respective logos are

trademarks or registered trademarks of SAP AG in

Germany and in several other countries all over the

world. All other product and service names mentioned

are the trademarks of their respective companies. Data

contained in this document serves informational

purposes only. National product specifications may vary.

These materials are subject to change without notice.

These materials are provided by SAP AG and its affiliated

companies ("SAP Group") for informational purposes

only, without representation or warranty of any

kind, and SAP Group shall not be liable for errors or

omissions with respect to the materials. The only

warranties for SAP Group products and services are those

that are set forth in the express warranty statements

accompanying such products and services, if any.

Nothing herein should be construed as constituting an

additional warranty.

These materials are provided “as is” without a warranty

of any kind, either express or implied, including but not

limited to, the implied warranties of merchantability,

fitness for a particular purpose, or non-infringement.

SAP shall not be liable for damages of any kind including

without limitation direct, special, indirect, or

consequential damages that may result from the use of

these materials.

SAP does not warrant the accuracy or completeness of

the information, text, graphics, links or other items

contained within these materials. SAP has no control

over the information that you may access through the

use of hot links contained in these materials and does not

endorse your use of third party web pages nor provide

any warranty whatsoever relating to third party web

pages.

SAP NetWeaver “How-to” Guides are intended to

simplify the product implementation. While specific

product features and procedures typically are explained

in a practical business context, it is not implied that those

features and procedures are the only approach in solving

a specific business problem using SAP NetWeaver. Should

you wish to receive additional information, clarification

or support, please refer to SAP Consulting.

Any software coding and/or code lines / strings (“Code”)

included in this documentation are only examples and

are not intended to be used in a productive system

environment. The Code is only intended better explain

and visualize the syntax and phrasing rules of certain

coding. SAP does not warrant the correctness and

completeness of the Code given herein, and SAP shall

not be liable for errors or damages caused by the usage of

the Code, except if such damages were caused by SAP

intentionally or grossly negligent.

- 1 -

1 Business Scenario

SAP MDM is the ideal solution to build a central repository for master data and their related customizing from heterogeneous landscape. It helps to build the key mapping between same or similar objects from different systems. This key mapping information is very valuable and is requested in many application scenarios regarding master data objects: global spend analysis, global sales reports… But there are other IT scenarios that enable you to benefit from this consolidation work done in MDM: mapping during data exchange in cross systems business scenarios, like unit of measures, basic material, … This document will explain how to export the key mapping information from MDM into XI value mapping table to enable direct communication of business document with value transformation between different systems. The benefits are multiple:

- leverage MDM mappings knowledge - one single version of truth (MDM) easy to maintain with some matching

capabilities, quickly replicated in XI. - independency of XI running processes and MDM availability (no direct access)

As a final remark, it’s not recommended to use this value mapping table for big amounts of data because of performances impacts. It’s recommended then to use MDM JAVA API calls to directly retrieve the key for target system.

2 Introduction

As we are going to use MDM and XI, it is mainly recommended having a good knowledge on XI configuration and MDM Syndicator. Some experience around XML and XSD could also help to understand underlying principles. Some basic java programming is needed to be able to create a simple jar file, at least to compile a Java source. The solution relies on XI capability to receive and store value mappings in dedicated tables through a specified interface (provided by XI). You should have your own Product defined in XI’s SLD, with an additional dependency for installation time to the SAP_BASIS 6.40 software component version. Then you have almost all needed prerequisite to setup your interface.

A very important prerequisite in the source table of MDM repository is the availability of one field (or a field combination) with unique value in the table. This can be ensured in two different ways : - include a field type AutoId in the table - activate on the table (with key mapping to export) a unique field or field combination (repository definition in MDM Console) This field will be use as a GroupId generator later in the document to define common identification of an object across the landscape.

- 2 -

3 The Step By Step Solution

3.1 Register JAVA inbound proxy for value mapping table reception in XI

As documented in SAP online documentation (here), you must input the following string in your browser to activate the mass enabled interface for value mapping table. Here we activate the asynchronous interface which is recommended.

http://<Server>:<Port>/ProxySe

rver/register?ns=http://sap.co

m/xi/XI/System&interface=Value

MappingReplication&bean=locale

jbs/sap.com/com.sap.xi.service

s/ValueMappingApplication&meth

od=valueMappingReplication

Remarks:

- This activation is only needed once for each system

- You need a user and password with required JAVA authorization to activate this proxy

- 3 -

3.2 Define an XSD from XI ValueMappingReplication for MDM Syndicator

1. As the MDM syndicator does not support yet the namespaces and target namespaces for tag element definitions, we have to make a slight change of the XSD for interface mapping. To retrieve the ValueMappingReplication standard XSD, navigate into the Repository builder as show : you can here download the current XSD from XI. Save a copy of it in a local folder on your computer.

2. You can use any text editor to delete the highlighted attributes in the file to keep only the following string at the beginning of the file: <?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> Save the file as ValueMappingReplication_MDM.xsd

3. Import this XSD in the repository to enable Syndicator mapping. Using the console, unload the repository, navigate to XML Schemas in the Admin tree, right click in the upper-right area to add XML schema, input a description , select the file createdbefore, and save all by pressing Shift+Enter. This XSD will be used later in the syndication map. Note: if you update the XSD after that initial load, change the file name and update it in the console to ensure update is done.

- 4 -

4. Import the same XSD in XI repository builder: open your software component, create a new external definition as shown here with a right click on the “External definitions” node. Input name accordingly to your naming conventions.

:::

5. Choose XSD category and then upload your file in XI. Save it.

- 5 -

3.3 Create a JAVA program to generate a global unique identifier during message mapping

The Value Mapping interface needs a GroupID that represent the common identifier for all possible values of the same object instance on the different clients systems. Because MDM does not generate GUID in the string 32 format (MDM Autoid field type is integer), we need to generate from this identifier a GroupID which is unique across the value mapping table for the schema (object type). This is done thanks to a standard SAP java class we will encapsulate.

1. With Netweaver developer studio or any JAVA workbench, create a JAVA class to embed com.sap.guid classes available in the SAP Web Application Server. It’s not possible to call them directly from the user-defined functions in the graphical mapping tool. This coding is provided as annex in this document. Then generate a JAR file to import it into XI in the next step. Note : you can implement your own algorithm, but the interface expects a string of 32 characters for this GroupID parameter

2. Import the generated JAR file into XI repository : Right click on the imported archives under mapping objects to access the new menu, and input a name.

- 6 -

3. Import the created Jar file in the repository and save it .

3.4 Create a message mapping from MDM to XI value mapping message with GUID enrichment

1. Right click on message mapping to create a new one. Input a name and choose Create.

2. Select the source message from the repository list...

- 7 -

3. Select the previously imported external definition of ValueMappingReplication definition of your namespace.

4. Repeat the action for the target message, but in the standard http://sap.com/xi/XI/System namespace. It should exist in your software component if inheritance has been defined in SLD, otherwise you have to browse to the SAP BASIS -> SAP BASIS 6.40 software component to find it.

5. Select root nodes of source and target message and use the Automap feature. Because the message structure are almost identical, all the fields will be correctly mapped, but further rework remain for the GUID generation on the GroupID element.

- 8 -

6. Double click on the GroupID target element to edit the current mapping and create a new Function to call the previously generated Java coding

7. Input the field accordingly to the screen copy with your own naming convention if any. Note : default argument “a” was renamed to Group_Id

8. Add the import the the previously created class com.sap.ph.myGUID.MyGUID; Then insert the simple following coding to call the defined function : return MyGUID.GetGUID(Group_Id);

Save and close.

- 9 -

9. Now use the created function between sending and receiving element to generate the GUID : choose user-defined functions, drag and drop on the mapping area, and change arrows to get this mapping

10. You can save and test the mapping. A sample for testing is provided in the annex. The fact is that for the same string as input, you’ll always get the same GUID as output. That’s why it’s important that your MDM source table contain a field that will ensure this uniqueness.

- 10 -

3.5 Create a message interface outbound for MDM relying on the imported XSD mapping

1. In the interface Objects sub-tree, create a new message interface for MDM messages outgoing from the syndication.

2. Select the interface as outbound asynchronous (defaults) and browse to the external definition imported for MDM. Save it.

3.6 Create an interface mapping using the previously defined message mapping from MDM message to XI message interface

1. In the Mapping Objects sub-tree, create a new interface mapping to map the MDM adjusted Value Mapping message interface to the standard XI Value Mapping message interface.

2. Put the cursor in the sender interface name to access the value-help, and select your interface ValueMappingReplication_MDM_Message_out

- 11 -

3. Repeat step 2 to fill up the receiving interface with the standard interface ValueMappingReplication from http://sap.com/xi/XI/System namespace. Importante note : if you did not link SAP BASIS 6.40 software component to your own software component in the SLD , you will have to browse to browse to SAP BASIS->SAP BASIS 6.40 to find this message interface.

4. Read interfaces to update the fields for source and target message and find quickly the only mapping object available for that combination

5. Select the field for mapping program to access to value-help: only the previously defined message mapping should be able to deal with these messages. Select it and save the interface mapping.

6. Activate your work in the Change Lists with a right click on the standard Change List, Activate menu.

- 12 -

7. Check that all items you have created are in the list and choose the Activate button. Now we have done all the repository work and you can configure this interfaces knowledge in the configuration builder.

- 13 -

3.7 Configure XI directory and define required business services: defining XI system possible messages and communication channels.

There are many options to declare communicating systems in XI. We present here only the fastest method.

1. In the configuration builder, right click on the first entry to create your own configuration scenario. It will group all needed objects together. Save it.

2. Create business service that will represent XI system.

3. Add the messages interfaces the XI system is supposed to be able to receive. Select here ValueMappingReplication from standard http://sap.com/xi/XI/System namespace. Save it.

4. Now create communication channel for XI incoming messages.

- 14 -

5. Select XI adapter type to get the additional parameters for the Java inbound Proxy

6. As documented in the on-line help (click here to access it), input the following parameters adapted to your own server hostname and port in your landscape. Prefer “xiappluser” to be sure to get all needed authorizations for runtime. Save the communication channel definition .

- 15 -

3.8 Define business service for MDM server with supported messages and communication channel.

1. Create in the same way the MDM server business service sender of the MDM message containing the Value Mapping.

2. Add the message interface the MDM system is supposed to be able to send. Select here ValueMappingReplication_MDM_Message_out. Check it is the right namespace and software component Save it.

3. Create now a communication Channel for MDM.

4. Choose the file adapter to define the common file or ftp folder both systems can access (XI and MDM). Actually, MDM can only send XML through file interface.

- 16 -

5. Configure according to your landscape the file interface. Note: you can switch to ftp in the transport protocol drop-down entry. The pool interval has been reduced here to minimize the wait time for demo purposes.

Save the communication channel definition.

3.9 Configure the message routing and mapping in XI with the wizard.

1. A very nice feature of XI is this wizard that help you to configure quickly and easily the message processing in XI. Choose the wizard button to start it, and choose internal scenario.

2. For the inbound message, configure MDM server as sender with the value-help. Pay attention to select Business Service otherwise you will not find your business service defined before. Then press the continue button for next step.

3. For the outbound message, configure XI_mapping_receiver as sender with the value-help. Pay attention to select Business Service otherwise you will not find your business service defined before. Then press the continue button for next step.

- 17 -

4. No sender agreement can be configured directly here, so go to next step. We will define the sender agreement later.

5. Receiver determination will be created automatically for this combination. No change is needed here, go to next step.

6. Interface determination will also be created automatically. The system found the only available mapping for this message combination and assigned it to this object. Check if it’s correct, and go to next step.

7. Here the system found also the only available communication channel for receiving partner, and assigned to it. Check it is correct also and choose continue.

8. Here you can choose in which scenario the created object will be assigned. The default (created scenario in part 3.7) should be the correct one. Then press the finish button.

9. The configuration wizard log enable you to check what objects have been reused or created, and to access all of them from here.

- 18 -

10. You have to create manually a sender agreement that will allow MDM server to send ValueMapping_replication_Message_out by the communication channel defined before. Select the MDM business service and corresponding interface.

11. Select the previously created communication channel with the value-help.

Save your work.

12. Activate changes in the change lists tab : check all your entries are selected and activate them. Now XI is configured and ready to receive any value mapping replication message to create or delete entries in its local value mapping tables.

- 19 -

3.10 Create a MDM syndication map to export key mapping to XI.

1. Start the MDM Syndicator on the repository with the mapping table to export. In the file menu, choose the destination properties :

2. Select the XML schema imported earlier, and one of the client system connected to the repository.

3. Choose then the table mapping content to export (here material types)

4. Right click on the source item [Remote Key] to expand it and display also systems

5. In this example, we ensured that “Code” is unique: we can use it as a “GroupId”. So map “Code” to “GroupID”, and “Remote key” to “Identifier”. Last, map “Client System” to agency. Note: for generic use in XI mapping function, you should use in MDM console the business service name, or party, or business system as defined in XI directory.

- 20 -

6. Mapping “Material Types” root node to “Item” node makes the system creating one file for all selected records. If you don’t do that, you’ll get one file per record.

7. Operation target field will get a fixed value “Insert” to add this value in the XI mapping table. (see ValueMappingReplication XSD documentation for possible options). Double click on the source column to input fixed value.

8. Repeat the action to input following fixed values: - Context = “http://com.sap/ph/MDM” free string to group different mappings together - Scheme = “MaterialType” free string to define the object type mapped in the context

9. In the map Properties tab, check the suppress records without key to avoid sending empty mappings, otherwise errors may occurred during posting. Add all client systems for which you want to export key mappings in the selected clients systems list.

10. Save mapping to store this mapping in the repository.

- 21 -

3.11 Sending MDM key mappings and check result in XI

1. Start Syndicator, load the previously defined map. Check the export content if needed in the preview tab and execute syndication.

2. Save the file(s) generated in the previously defined XI communication channel for MDM. Be carefull on the naming if you have defined special naming conventions in XI communication channel.

3. All mappings have then been exported to file system. XI file adapter read the file, send it to Itegration server, which have mapped it to generate the GroupID, and send then it to the java proxy for value mapping.

- 22 -

4. You can check the result in the runtime workbench monitoring, on the cache monitoring: as shown here as an example, FERT is available for both systems, but they are not in the same GroupID. The details on QRM_510 system shows that this value is mapped to ZFER for client system QZA_510.

- 23 -

3.12 Additional hints for XI value mapping table monitoring, deletion and updates

1. You must use the Java Monitoring workbench to check posting of message in JAVA proxy, through the adapter monitoring. SXMB_MONI transaction only monitors the routing and mapping of message from the sender adapter to the receiver adapter. In this exemple, routing and mapping runs fine, but posting lead to errors because of incorrect value for <Operation>.

2. You can easily delete a full context by copying a XML file similar to this one in the MDM communication channel: all the context can be deleted (copy of this XML in annex). Just adapt the tag <Context> to your own value. In this case, identifier tag is not interpreted and can contain any string.

3. .As documented in the XSD, no update operation is possible for <Operation> tag. As a consequence, it is safer and easier to delete a context and resend the full mappings. To avoid many schemes deletion, it’s then simpler to have one context per scheme.

4. When defining mapping in a cross systems scenario, you can retrieve this key mapping thanks to a predefined SAP functions in the graphical mapping tool. Just fill up the properties with the defined values of your mapping context, and mapping will be done during runtime. Important note : you cannot test the result in the graphical mapping tool test as it cannot .access the proxy. To check the result, you must use the test configuration tool in the Configuration builder (since SP12, documented in SDN here), or use the SXI_SUPPORT transaction.

- 24 -

Appendix (<<e.g. Coding, …..>>)

• JAVA coding for GUID generation : /*

* Created on 18-Nov-2005

*

* To change the template for this generated file go to

* Window&gt;Preferences&gt;Java&gt;Code Generation&gt;Code and Comments

* Imported classes are available in the XI jar file

* Can be found in the following folder :

* usr\sap\<SID>\JC00\j2ee\cluster\server0\bin\ext\com.sap.guid

* Important note : IGUID interfaces is not released for public use

* and may be changed without prior notice.

* No support will be provided on this package use.

*/

package com.sap.ph.myGUID;

import com.sap.guid.GUIDGeneratorFactory;

import com.sap.guid.IGUID;

import com.sap.guid.IGUIDGenerator;

import com.sap.guid.IGUIDGeneratorFactory;

/**

* @author Pierre Hugot

*

* To change the template for this generated type comment go to

* Window&gt;Preferences&gt;Java&gt;Code Generation&gt;Code and Comments

*/

public final class MyGUID {

static public String GetGUID( String StrInput ){

IGUIDGeneratorFactory factory = GUIDGeneratorFactory.getInstance();

IGUIDGenerator generator = factory.createGUIDGenerator();

IGUID guid_str = generator.createGUID(StrInput);

return guid_str.toHexString();

}

}

- 25 -

• ValueMappingReplication Sample for mapping testing : <?xml version="1.0" encoding="UTF-8"?>

<ValueMappingReplication>

<Item>

<Operation>Insert</Operation>

<GroupID>test2</GroupID>

<Context>http://com.sap/ph/MDM</Context>

<Identifier scheme="PHObjectType" agency="PHClientSystem">

PHClientSyst_key

</Identifier>

</Item>

</ValueMappingReplication>

• XML sample for deletion of full context of value mapping table <?xml version="1.0" encoding="UTF-8"?>

<ValueMappingReplication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<Item>

<Operation>Delete</Operation>

<GroupID>12345678901234567890123456789012</GroupID>

<Context>http://com.sap/ph/MDM</Context>

<Identifier scheme="MaterialType" agency="QZA_510">00000007</Identifier>

</Item>

</ValueMappingReplication>

• Links to XI documentation related to value mapping tables : Java proxy activation and Value mapping replication for mass data interface documentation : http://help.sap.com/saphelp_nw04/helpdata/en/2a/9d2891cc976549a9ad9f81e9b8db25/frameset.htm Communication channel configuration for inbound proxy of Value mapping tables : http://help.sap.com/saphelp_nw04/helpdata/en/5b/12b7e6a466456aa71ef852af033b34/frameset.htm Value mapping runtime execution advanced SAP Java API library : http://help.sap.com/saphelp_nw04/helpdata/en/f2/dfae3d47afd652e10000000a114084/frameset.htm SDN blog documentation : https://www.sdn.sap.com/irj/sdn/weblogs?blog=/pub/wlg/1924

www.sdn.sap.com/irj/sdn/howtoguides