TBIT44 - 2004-Q4 - A4 - Mapping, Adapters and BPM

© SAP AG <Course Number> Course Overview - 1

©SAP AG 2004

TADMBO Implementation&Operation II

THE BEST-RUN BUSINESSES RUN SAP

© SAP AG 2004

TBIT44

Mapping, Adapters and BPM

„

2004/Q4

©SAP AG

TBIT44

0 - 1

SAP Exchange Infrastructure 3.0

©SAP AG

TBIT44

0 - 2

Topics

Lecture topics

TBIT40 Exercise 0: Preparations

Page 1 of 1

Exercise 0: Preparation Overview

The purpose of this exercise is to create general objects in SLD, Repository, and Directory. In all exercise descriptions: ## is the placeholder for your group number.

Exercise steps

*Please note, as a general rule, all development and configuration objects are CASE-SENSITIVE.

SLD

1. Logon to the SLD, e.g using transaction SLDHTMLGUI.

2. Create a Software Component Version (SWCV): in the Software Catalog under Components create SWCV TBIT44_## for Product ATP (2004) from vendor SAP,

version 1.0.

3. Maintain a usage dependency of your SWCV TBIT44_## to the following SWCVs: - SELLSPAREPARTS, 1.0 of SAP

- TBIT44, 2004 of SAP

- TBIT44_BASE_COMP, 1.0 of SAP (dependency context: “Installation time”).

4. Add your SWCV to be used in the technical systems:

R/3 backend (Technical System Type: Web AS ABAP)

XI system (Technical System Type: Web AS ABAP)

TBIT44_FILE_SENDER (Technical System Type: Third-Party)

TBIT44_JDBC_RECEIVER (Technical System Type: Third-Party)

DMSCRM (Technical System Type: Third-Party)

DMS_CRM (Technical System Type: Third-Party)

Navigate to the detail view on these technical systems, choose the product ATP (under “Installed Products”), select your SWCV and save.

Integration Repository

5. Logon to the Integration Repository, e.g using transaction SXMB_IFR.

6. Import your SWCV TBIT44 _## via menu “Tools/Transfer from System Landscape Directory / Import Software Component Versions...”.

7. Create namespaces: create the following four namespaces in your SWCV:

urn:sap-com:TBIT44:adapters:group## urn:sap-com:TBIT44:BPM:group## urn:sap-com:TBIT44:mapping:group## http://www.sap.com/xi/BPM/Spareparts

(for the last namespace you will get a warning message because this namespace already exists in another SWCV, but you can create it.) 8. Save and activate your changes in Integration Repository.

Integration Directory

9.

10.

##.

11.

TBIT40 Part I: Mapping / Exercise 1

Page 1 of 1

Exercise 1: Message Mapping – Standard Functions Overview

The purpose of this exercise is to design a Message Mapping using standard functions of the mapping tool. This exercise will test the understanding of using standard functions in Message Mapping.

Prerequisites

Basic knowledge of XI 3.0 Message Mapping.

Description

The source is an XML document containing Contact1 information. The target is an XML document containing Customer1 information. Both can be found in your SWCV, under Basis

Objects, in namespace urn:sap-com:TBIT44:mapping:common. Exercise steps

*Please note, as a general rule, all development and configuration objects are CASE-SENSITIVE. There are many ways to achieve the desired result. The solution provided here is only 1 way, not the only way.

Create a Message Mapping

1. In the Integration Repository, go into your SWCV TBIT44_## and your namespace

urn:sap-com:TBIT44:mapping:group## (## is your group number) and create a new

Message Mapping called ContactToCustomer1 between Contact1 as source message and Customer1 as target message.

2. The target element fullname should contain the concatenated content of title, firstname

and custname, separated by a blank.

3. The first 10 digits of element contactID should be filled into element customerNo. 4. The six last digits of element contactID should be used to fill element birthday. Please

perform a date transfer so that birthday is of format yyyy/dd/MM.

5. Test the mapping (using the “Test” tab). You can use e.g. the following xml file for testing:

<?xml version="1.0" encoding="UTF-8"?> <ns0:Contact1 xmlns:ns0="urn:sap-com:TBIT44:mapping:common"> <title>Mr.</title> <custname>Smith</custname> <firstname>Paul</firstname> <contactID>0123456789-181170</contactID> </ns0:Contact1> Possible solution

/ns0:Customer/name/ firstname= /ns0:Contact/firstname

/ns0:Customer/name/surname =/ns0:Contact/custname

/ns0:Customer/name/fullname =concat ([delimeter= ]concat ([delimeter= ]/ns0:Contact/ title ,

/ns0:Contact/ firstname) , /ns0:Contact/custname )

/ns0:Customer/ birthday= DateTrans([iform=ddMMyy,oform=yyyy/dd/MM] substring([start=11,count=6] /ns0:Contact/contactID ))

TBIT40 Part I: Mapping / Exercise 2

Page 1 of 2

Exercise 2: Message Mapping – Mapping Template Overview

The purpose of this exercise is to design a Message Mapping using existing mapping templates. This exercise will test the understanding of using mapping template in Message Mapping.

Prerequisites

Basic knowledge of XI 3.0 Message Mapping.

Description

The source is an XML document containing Contact information. The target is an XML document containing Customer information.

Within Contact, predefined data types of Name and Address are used.

Within Customer, predefined data types of CustName and CustomerAddress are used. In a first step, two Mapping Templates based on these Data Types will be defined. Then the templates will be reused in a Message Mapping.

(The objects can be found in your SWCV, under Basis Objects, in namespace

urn:sap-com:TBIT44:mapping:common.) Exercise steps

*Please note, as a general rule, all development and configuration objects are CASE-SENSITIVE. There are many ways to achieve the desired result. The solution provided here is only 1 way, not the only way.

Create a Message Mapping

1. Logon to Integration Repository.

2. Go into SWCV TBIT44_## and your namespace urn:sap-com:TBIT44:mapping:group##.

3. Create a mapping template.

In Mapping Templates, create a template called NameToCustName, with the following mapping. The source and target are the data types of Name and

CustName.

Please note that Mapping Templates are created using Data

TBIT40 Part I: Mapping / Exercise 2

Page 2 of 2

4. Create a second Mapping Template AddressToAddress applying a simple identity mapping (between the data type Adress and Adress).

5. Create a Message Mapping ContactToCustomer between Contact and Customer (both Message Types).

6. Assign the Mapping Template as follow:

• Mark element Name in the source structure and element CustomerName in the

target structure

• Right-click on element CustomerName and select “Show Suitable Templates”

• Select your mapping template NameToCustName.

7. Do the same for Address and CustomerAddress (using template AdressToAddress).

8. Check your mappings.

TBIT40 Part I: Mapping / Exercise 3

Page 1 of 2

Exercise 3: Message Mapping – Context Handling Overview

The purpose of this exercise is to design a Message Mapping utilizing basic standard XI 3.0 functions.

This exercise will test the understanding of context/queue processing of Message Mapping.

Prerequisites

Basic knowledge of XI 3.0 Message Mapping.

Description

The source is an XML document containing material information. This document contains a material number and its description in multiple languages.

The result of the mapping/transformation will contain the material number and the description of the material in English.

Example source XML: <?xml version="1.0" encoding="UTF-8"?> <ns0:MATERIAL xmlns:ns0="http://xi.com/mapping/exercise3"> <MATNO>4711</MATNO> <MATTEXT> <LANGKEY>DE</LANGKEY> <TEXT>Zahnpasta</TEXT> </MATTEXT> <MATTEXT> <LANGKEY>EN</LANGKEY> <TEXT>toothpaste</TEXT> </MATTEXT> <MATTEXT> <LANGKEY>FR</LANGKEY> <TEXT>dentifrice</TEXT> </MATTEXT> </ns0:MATERIAL>

Result of the mapping/transformation:

<?xml version="1.0" encoding="UTF-8"?> <ns0:ProductDefinition xmlns: ns0="http://xi.com/mapping/exercise3"> <RefNo>4710</RefNo> <Description>toothpaste</Description> </ns0:ProductDefinition> Exercise steps

*Please note, as a general rule, all development and configuration objects are CASE-SENSITIVE. There are many ways to achieve the desired result. The solution provided here is only 1 way, not the only way.

TBIT40 Part I: Mapping / Exercise 3

Page 2 of 2

Create a Message Mapping

1. Logon to Integration Repository.

2. Go into your SWCV TBIT44_## and your namespace

urn:sap-com:TBIT44:mapping:group##.

3. Create a Message Mapping object named MATERIALToProductDefinition. 4. Use Message Type MATERIAL as source and ProductDefinition target structure.

5. To achieve the mapping requirement, we need to do the following: a. The MATNO from source is mapped to RefNo of target.

b. Test the content of LANGKEY for the value of “EN”, for English.

c. Assign the appropriate TEXT matching the LANGKEY to Description of the target.

6. Create the following mappings in the Data Flow Editor:

Please note that all italicized source element name has context of “MATERIAL”.

Hint: for content check of LANGKEY, use text function equalsS

7. Test the mapping by using the “Test” tab. Create at least three different entries of node MATTEXT using the duplicate subtree function. You can use the example for the source XML of the Description part of the exercise as role-model.

TBIT40 Part I: Mapping / Exercise 4

Page 1 of 6

Exercise 4: User-defined functions – part I Overview

The purpose of this exercise is to design a Message Mapping utilizing some basic techniques of using advanced user functions and to test the understanding of context/queue processing.

Prerequisites

Advanced knowledge of XI 3.0 Message Mapping. Basic knowledge of Java.

Description

The source is an XML document containing purchase order information. This document contains multiple orders. Each order has 1 header and multiple items information.

The result of the mapping/transformation will contain a row for each item. Each row will contain the header information from the source, and the item information.

This mapping might be used when we want to insert into a table the content of a purchase order from an IDoc. Each row in the table must contain both the header and detail information. For example, the source contains 2 orders. Each order has a header and 2 items. The result of the mapping/transformation must contain 4 rows for each of the items in the source. In addition, each of the rows will also contain the corresponding header information.

Example source XML: <?xml version="1.0" encoding="UTF-8"?> <PurchaseOrder> <Order> <Header> <Name>Smith</Name>

<Address>123 Main St.</Address> </Header> <Item> <Material>100</Material> <Units>2</Units> <Price>100</Price> </Item> <Item> <Material>200</Material> <Units>1</Units> <Price>10</Price> </Item> </Order> <Order> <Header> <Name>Jones</Name>

<Address>987 First Ave.</Address> </Header> <Item> <Material>101</Material> <Units>3</Units> <Price>50</Price> </Item> <Item> <Material>201</Material> <Units>4</Units> <Price>1000</Price> </Item> </Order> </PurchaseOrder>

TBIT40 Part I: Mapping / Exercise 4

Page 2 of 6

Result of the mapping/transformation:

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

<row>

<name>Smith</name>

<address>123 Main St.</address> <material>100</material> <units>2</units> <price>100</price> </row> <row> <name>Smith</name>

<address>123 Main St.</address> <material>200</material> <units>1</units> <price>10</price> </row> <row> <name>Jones</name>

<address>987 First Ave.</address> <material>101</material> <units>3</units> <price>50</price> </row> <row> <name>Jones</name>

<address>987 First Ave.</address> <material>201</material> <units>4</units> <price>1000</price> </row> </resultset> Exercise steps

*Please note, as a general rule, all development and configuration objects, especially Java codes, in XI are CASE-SENSITIVE.

There are many ways to achieve the desired result. The solution provided here is only 1 way, not the only way.

Create a Message Mapping

1. Logon to Integration Repository and go into your SWCV TBIT44_## and your namespace

urn:sap-com:TBIT44:mapping:group##.

2. Create a Message Mapping object named PO_to_resultset.

3. Insert message types PurchaseOrder as source and resultset as target (from Basis

objects, namespace urn:sap-com:TBIT44:mapping:common). 4. The result should look like the following:

TBIT40 Part I: Mapping / Exercise 4

Page 3 of 6

5. To achieve the mapping requirement, we need to do the following:

a. With each row in resultset, we need to assign the Header information from PurchaseOrder. This need to be done for both Name and Address.

b. The remainder elements in row can map directly from source to target. 6. Create the following Advanced User Function:

copyPerValue – There are 2 arguments. The 1st argument is the item, the 2nd argument is the Name or Address. In each context, for each occurrence of the item, the function will add the Name or Address to the target.

TBIT40 Part I: Mapping / Exercise 4

Page 4 of 6

8. Test the mapping by using the “Test” tab. Enter the following data as an example.

TBIT40 Part I: Mapping / Exercise 4

Page 5 of 6

TBIT40 Part I: Mapping / Exercise 4

Page 6 of 6

Bonus Exercises:

I. To send a trace message to SXMB_MONI, use the Container object in either Simple or Advanced user–function. Create a Simple user–function sendTraceInfo with 1 argument:

To use it, we can do the following mapping:

The testing tool will not be able to test the trace info being sent to the monitor. Only during runtime, the trace info will be sent to the monitor. In addition, the monitor’s trace level must be properly set to display it.

II. Control our own context changes in user–function.

In the exercise, we used the Node Function, SplitByValue, to insert context changes between the values. We can also perform this function within our own user–function. We can replace our user–function, copyPerValue, with another function,

copyPerValueWithCC:

TBIT40 Part I: Mapping / Exercise 5

Page 1 of 8

Exercise 5: User-defined functions – Part II Overview

Purpose of this exercise: to design a Message Mapping utilizing advanced user functions along with the standard XI 3.0 functions; it will test the understanding of context/queue processing.

Prerequisites

Advanced knowledge of XI 3.0 Message Mapping. Basic knowledge of Java.

Description

The source is an XML document containing purchase order information. This document contains a single header with multiple detailed purchase orders. In each detailed purchase order, the supplier’s name is provided. There can be more than 1 detailed purchase order per supplier, and the number of suppliers is unknown. The detailed purchase orders are not grouped by supplier, in another word, it is not sorted by supplier name.

The result of the mapping/transformation will contain an order for each supplier. Each supplier will contain the header information from the source, and all the detailed purchase orders belonging to the same supplier must be grouped within the order.

For example, the source contains 2 suppliers and 4 detailed purchase orders. The 2nd and 3rd detailed purchase orders belong to companyA, and the 1st and 4th detailed purchase orders belong to companyB. The result of the mapping/transformation must contain 2 orders, each with a header. For companyA’s order, it must contain the 2nd and 3rd detailed purchase orders. For companyB’s order, it must contain the 1st and 4th detailed purchase orders.

Example source XML: <?xml version="1.0" encoding="UTF-8"?> <ns9:POCombined xmlns:ns9="http://sap.com/xi30/mapping/patterns"> <Header> <Name>myName</Name> <Address>myAddress</Address> </Header> <Detail> <Supplier>OfficeMax</Supplier> <ProductID>11</ProductID> <Quantity>12</Quantity> <Price>13</Price> </Detail> <Detail> <Supplier>OfficeDepot</Supplier> <ProductID>21</ProductID> <Quantity>22</Quantity> <Price>23</Price> </Detail> <Detail> <Supplier>OfficeDepot</Supplier> <ProductID>31</ProductID> <Quantity>32</Quantity> <Price>33</Price> </Detail> <Detail> <Supplier>OfficeMax</Supplier> <ProductID>42</ProductID> <Quantity>42</Quantity> <Price>43</Price> </Detail> </ns9:POCombined>

TBIT40 Part I: Mapping / Exercise 5

Page 2 of 8

Result of the mapping/transformation:

<?xml version="1.0" encoding="UTF-8"?> <ns9:POSplit xmlns:ns9="http://sap.com/xi30/mapping/patterns"> <Orders> <Header> <toCompany>OfficeMax</toCompany> <custName>myName</custName> <custAddress>myAddress</custAddress> </Header> <Items> <productNo>11</productNo> <quantity>12</quantity> <price>13</price> </Items> <Items> <productNo>42</productNo> <quantity>42</quantity> <price>43</price> </Items> </Orders> <Orders> <Header> <toCompany>OfficeDepot</toCompany> <custName>myName</custName> <custAddress>myAddress</custAddress> </Header> <Items> <productNo>21</productNo> <quantity>22</quantity> <price>23</price> </Items> <Items> <productNo>31</productNo> <quantity>32</quantity> <price>33</price> </Items> </Orders> </ns9:POSplit> Exercise steps

*Please note, as a general rule, all development and configuration objects, especially Java codes, in XI are CASE-SENSITIVE.

There are many ways to achieve the desired result. The solution provided here is only 1 way, not the only way.

Create a Message Mapping

1. Logon to Integration Repository and go into SWCV TBIT44_## and namespace

urn:sap-com:TBIT44:mapping:group##.

2. Create a Message Mapping object called POCombinedToSplit.

3. Select Message Type POCombined as source structure and POSplit as target structure

TBIT40 Part I: Mapping / Exercise 5

Page 3 of 8

4. The result should look like the following:

5. To achieve the mapping requirement, we need to do the following:

a. Determine the number of unique suppliers. This is how many Orders we must create in the target.

b. Assign the Header information to each of the Orders in the target. c. Determine the number items for each supplier.

d. Assign the Detail information to the Items to the appropriate supplier in the target. 6. Create the following 4 Advanced User Functions:

getSuppliers – using Supplier as the input parameter, this function tests all the Supplier

TBIT40 Part I: Mapping / Exercise 5

Page 4 of 8

assignItems – using Supplier as the input parameter, this function determines how many

Items belongs to each Supplier and separate them with a ContextChange. In another word, for each Supplier, it create the number of Items element for it.

assignValue – using the number of unique Supplier as input, that same number of the

value in the 2nd parameter will be added to the output. So, if there are 2 Suppliers, then the value in the 2nd parameter will be copied 2 times.

TBIT40 Part I: Mapping / Exercise 5

Page 5 of 8

assignSupplier – this function is to assign the elements in Detail to the appropriate

Items of a Supplier’s Order. It is used to rearrange/reorder the elements in Detail corresponding to how the Items are grouped together based on the Supplier.

TBIT40 Part I: Mapping / Exercise 5

Page 6 of 8

Please note that all italicized source element name has context of “POCombined”.

TBIT40 Part I: Mapping / Exercise 5

Page 7 of 8

8. Test the mapping by using the “Test” tab. Enter the following data as an example.

1

2

Mapping Patterns

Mapping “patterns” are some of the common mapping

requirements we found in the past which XSLT was used, because

we did not think that Message Mapping provided the functionality

Summarization

Sequence–Number Generation

Duplicating Subtrees

Table / Value Lookups

Tree–Reversal

3

Summarization is when we try to consolidate detailed information into total/subtotals and counts.

The count and sum functions will act on the content of a context. Therefore, the context of the group to be summarized must be selected appropriately.

Example:

Mapping Patterns – Summarization (I)

Target: Total and count the order by each customer and a summary of all orders

Source: Order details containing customer, order numbers and order amount

4

5

Mapping Patterns – Summarization (III)

Mapping Result:

6

Mapping Patterns – Sequence–Number Generation (I)

There are situations when sequence numbers had to be generated based

on the number of occurrences of the source data. This is frequently used

during mapping to SAP IDocs or BAPIs when item number, which is no

available from the source, had to be entered.

Example:

Source: Order information.

Target: Two complex elements

had to be populated from the

source. Each one contains a

sequence number which matches

the position of the data in the

source.

7

Mapping Patterns – Sequence–Number Generation (II)

There are two ways the sequence number can be generated.

1.

Use Advanced User–Defined function to generate the sequence

number all at once.

2.

Use Simple User–Defined function to generate the sequence

number for each occurrence separately, keeping track of the

sequence number value previously generated.

8

Mapping Patterns – Sequence–Number Generation (III)

Use Advanced User–Defined function to generate the sequence

number all at once.

The java function creates the sequence number all at once based on the number of elements in the source.

9

Mapping Patterns – Sequence–Number Generation (IV)

Use Advanced User–Defined function to generate the sequence

10

Mapping Patterns – Sequence–Number Generation (V)

Use Advanced User–Defined function to generate the sequence

number all at once.

11

Mapping Patterns – Sequence–Number Generation (VI)

2.

Use Simple User–Defined function to generate the sequence number for

each occurrence separately, keeping track of the sequence number

value previously generated.

The sequence number is stored in the container object. Each time it is retrieved, incremented and saved.

12

Mapping Patterns – Sequence–Number Generation (VII)

Use Simple User–Defined function to generate the sequence number for

each occurrence separately, keeping track of the sequence number

value previously generated.

13

Mapping Patterns – Sequence–Number Generation (VIII)

Use Simple User–Defined function to generate the sequence number for

each occurrence separately, keeping track of the sequence number

value previously generated.

14

Mapping Patterns – Duplicating Subtrees (I)

Even if elements are shown to occur more than once in the XML instance according

to XML Schema Definition, they are only displayed once in the structure overview.

To assign source field(s) to multiple positions of an element in the target structure,

the element or the entire subree can be duplicated (copied) using the context menu

in the target structure.

Example:

Source: Accounting information with

adjustment type and amount.

Target: Two CurrencyAmt’s are to

be created. One is to credit one

account. The other is to debit

another account. The amount will

either be positive or negative

depending on the ADJTYPE.

15

Mapping Patterns – Duplicating Subtrees (II)

The subtree “CurrencyAmt” must be duplicated first. This will create 2

CurrencyAmt’s. One for credit, and one for debit.

16

17

Mapping Patterns – Duplicating Subtrees (IV)

Mapping Results:

18

Mapping Patterns – Table/Value Lookup (I)

During mapping, a lookup is necessary in a different subtree structure of the XML

document. This lookup process is easily accomplished using XSLT, since we can

navigate the XML document using absolute or relative “path” specification. In

Message Mapping, there is no facility to navigate the XML document.

In Message Mapping, we have to use the context of the different elements required

for the lookup. A Java function will be needed to perform the comparisons. And,

the matched values will have to be written to ResultList.

Example:

Source: Contains credit card information, with 2 subtrees. One is account

information (including account number, cost center, sub–account, card type, etc.)

The 2

_{subtree contains detailed billing information (including account number,}

date, billing amount, etc.)

Target: Contains only detailed billing information, but with each billing record, the

cost center, sub–account and card type from the account info record must also be

included. The account number in the detail is used to do the lookup of the account

information records.

19

Mapping Patterns – Table/Value Lookup (II)

Source:

Target:

20

Mapping Patterns – Table/Value Lookup (III)

Java Function:

The lookup’d value

must be written to the

ResultList.

21

Mapping Patterns – Table/Value Lookup (IV)

Mappings for all 3 elements are identical, except for the element names.

22

Mapping Patterns – Table/Value Lookup (V)

Mapping Results:

23

Mapping Patterns – Tree–Reversal (I)

Below is a mapping scenario which reverses the parent and child nodes. A “reverse” summarizations is also performed.

Source document:

Target document:

The products are to be sorted and totaled by prices with the ORDERID listed.

24

Mapping Patterns – Tree–Reversal (II)

The source document is organized by ORDERID, ITEM and price. The same

product can occur in more than 1 orders.

The target document is summarized by product with a total price and listed

within each product all the ORDERIDs. The same ORDERIDs can occur in more

than 1 products.

The mapping needs to reverse the organization of the source document.

Based on that, the following needs to be done using the contexts/queues used

by Message Mapping:

1.

Get a list of all the products. Since the same product can be in multiple orders,

we must eliminate the duplicates, and, then, sort them.

2.

Sum the prices by product and assign those totals to the products in their sorted

order.

3.

Examine all the ORDERIDs and determine which ORDERIDs contain each of the

products in the sorted list. Then, assign those ORDERIDs to the products.

25

Mapping Patterns – Tree–Reversal (III)

Three Java functions were written to:

26

Mapping Patterns – Tree–Reversal (IV)

27

Mapping Patterns – Tree–Reversal (V)

3. Retrieve all the orderids and assign them to the appropriate products.

Note:

“Cache Entire Queue” is checked. When the product is being retrieved, the Context Change is skipped.

The Context Change is added to the ResultList.

28

Mapping Patterns – Tree–Reversal (VI)

29

Mapping Patterns – Tree–Reversal (VII)

30

Mapping Patterns – Tree–Reversal (VIII)

31

Mapping Patterns – Tree–Reversal (IX)

32

Mapping Patterns – Tree–Reversal (X)

33

Mapping Patterns – Tree–Reversal (XI)

34

Mapping Patterns – Tree–Reversal (XII)

35

Mapping Patterns – Tree–Reversal (XIII)

36

Mapping Patterns – Tree–Reversal (XIV)

Partial listing of the mapping results:

TBIT44 Adapters: CPA Cache 1

TBIT44 Adapters: CPA Cache 2

©SAP AG 2004, TBIT44: Adapters: CPA Cache / 2

Learning Objectives

As a result of this unit, you will:

„

Understand the basics of CPA Cache, including:

z Configuration

z Monitoring

z Troubleshooting

TBIT44 Adapters: CPA Cache 3

©SAP AG 2004, TBIT44: Adapters: CPA Cache / 3

Cache overview

•Full via URL

SLD Cache Business systems SLD Cache Software components versions “Based On” Business system

SLD Cache “Own Business system” •Activate Changelist

•Import

•Request Cache update again

•Business Process Configuration •Routing Rules •Collaboration Agreements •Collaboration Profiles

Local Adapter Engine

Adapter Framework Cache

J2EE: CPACache

•Delta

•Full via URL

SLD Cache “Own Business system”

Repository Cache

Adapter Meta data

TBIT44 Adapters: CPA Cache 4

©SAP AG 2004, TBIT44: Adapters: CPA Cache / 4

CPA Cache in general

ƒ

cache for Directory & Repository data (CPACache)

Æ

cache is filled during activation within directory

(process described at the end of the document)

ƒ

contains objects from directory

• services

• parties

• bindings (inbound/outbound; sender/receiver

agreements)

• channels

• adapter metadata

• module configuration

TBIT44 Adapters: CPA Cache 5

©SAP AG 2004, TBIT44: Adapters: CPA Cache / 5

CPA Cache – display content

Æ

data can be seen in the CPACache Monitor

(not accessible per default)

http://<host>:<J2EEport>/CPACache

„ Per default no user has access to the CPACache display tool

TBIT44 Adapters: CPA Cache 6

©SAP AG 2004, TBIT44: Adapters: CPA Cache / 6

CPA Cache – display content (2)

Æ

displays objects relevant for adapter framework during

runtime

„ Shows all CPA Cache content objects

„ E.g. bindings (inbound/outbound) , channels , adapter metadata, services, parties,

module configuration

„ Note: a binding corresponds to a sender or receiver agreement in the Integration

Directory. The direction will be inbound (I) or outbound (O), respectively.

TBIT44 Adapters: CPA Cache 7

©SAP AG 2004, TBIT44: Adapters: CPA Cache / 7

CPA Cache: Registration/Push vs. Pull

Registration/Push Mode

(automatically or manual)

PULL-Mode (Delta or Full Refresh)

„ Integration Directory => Environment => Cache Notifications

„ The AE Java Cache will execute a full cache refresh, the first time the engine gets

started

TBIT44 Adapters: CPA Cache 8

©SAP AG 2004, TBIT44: Adapters: CPA Cache / 8

CPA Cache refresh

Æ

manual refresh via URL with user “XIDIRUSER”

TBIT44 Adapters: CPA Cache 9

©SAP AG 2004, TBIT44: Adapters: CPA Cache / 9

CPA Cache refresh – in detail

Adapter Engine Notification handler Notif Directory Object Repository Object Changelist handler Update running

Get object ids Get Object

Get object from repository

OK / OK with errors Generalstatus

Notif error Error Status of single objects Runtime Cache Update XIAFuser XIDIRuser Directory Repository Adapter Engine

„ - after AE Runtime got the notification it starts the update asynchronously

„ - via JMS an update notification is written to the notification table

Æ can be seen in Directory Æ Environment Æ Cache Notifications

„ - the update of CPACache is done using the user XIAFUSER

„ - the objects from repository (metadata) are accessed from directory using user

„

XIDIRUSER

TBIT44 Adapters: CPA Cache 10

©SAP AG 2004, TBIT44: Adapters: CPA Cache / 10

SLD

CPA Cache - Registration

AE CPA Cache 1 Change in XI ID 2 ₄ 5 3

„ Enables decentral AE with central configuration

„ Current Registration Mode (alternative: pull from Adapter Engine)

„ All parties are loaded; communication channel objects only for the related AE

„ Step 1: ID contacts SLD to find out which adapter engines are registered, and the

URL where the trigger should be sent.

„ Step 2: ID sends a trigger to the respective adapter engines.

„ Step 3: adapter engine contacts the SLD to find out the address of the Integration

Directory

„ Step 4: cache refresh occurs between the ID and the AE.

„ Step 5: Cache status and detailed problem description can be seen in the

Integration directory: Environment => „Cache Notifications“ (positive and negative

confirmations)

TBIT44 Adapters: CPA Cache 11

©SAP AG 2004, TBIT44: Adapters: CPA Cache / 11

CPA Cache: Schema Upload

„ Information on available adapter schemas

„ Important for customer and partner solutions with the PCK; it is checked if the

cacheType is „PCK“: then one can upload schema with

http://<host>:<port>/CPACache/schemaupload.jsp

„ This is not necessary for standard SAP (technical) adapters shipped with the PCK

„ It is planned for the future that partners deliver and deploy their metadata with the

TBIT44 Adapters: Messaging System 1

TBIT44 Adapters: Messaging System 2

©SAP AG 2003, Title of Presentation, Speaker Name / 2

Learning Objectives

As a result of this unit, you will:

„

Understand the basics of the messaging system,

including:

z Messaging System overview

z Message flow

TBIT44 Adapters: Messaging System 3

©SAP AG 2003, Title of Presentation, Speaker Name / 3

Messaging system overview

XI

IS

DB

CPA Cache SPI Cache update XML Technical adapters File/JDBC/JMS/ Mail Other adapters without protocol handler RFC/SOAP/3rd party Adapter with protocol handler RNIF/BC/CDIX XI message Protocol handler ListenerBean exit MML/BC … message XI message XI message XI message XI “adapter” Protocol handler XI message Configuration Configuration PCK AFW ListenerBean •Read agreements •Read channels XI message SPI servlet servlet Convert Bean (Adapter specific) MML/BC … message URL URL

TBIT44 Adapters: Messaging System 4

©SAP AG 2003, Title of Presentation, Speaker Name / 4

Message status in MDT - Prerequisites

ƒ Open Runtime Workbench (RWB) ƒ Select Message Monitoring ƒ select adapter engine

TBIT44 Adapters: Messaging System 5

©SAP AG 2003, Title of Presentation, Speaker Name / 5

Example

ƒ you can use a simple file sender / receiver scenario to test the display of status ƒStart (activate) the sender and receiver channel

ƒStart (activate) only the sender channel, deactivate receiver channel

ƒ Start (activate) the receiver channel again

ƒ press button after selecting the message in “wait” mode

„ After stopping the receiver channel the message can not be delivered by the

adapter engine

„ The status “Delivering” is shown only for a short period while trying to deliver the

message

TBIT44 Adapters: Messaging System 6

©SAP AG 2003, Title of Presentation, Speaker Name / 6

Status overview of messages in MDT

NDLVD TBDL HOLD DLNG WAIT DLVD FAIL Worker thread Delivery exception

Scheduler/ Admin action successful

Recoverable exception

Max. retries exceeded

Admin action EOIO, wait for other message

„ TBDL : ToBeDeLivered, can only be seen as long as no worker thread has started

to process the message

„ DLNG: DeLiverNG

„ DLVD: DeLiVerD

„ HOLD: status if message waits for predecessors in EOIO mode

„ FAIL : a delivery exception occurred , no retry possible

„ WAIT:a recoverable exception occurred, retry possible, automatic retry by

scheduler or manual retry by admin action

„ NotDeLiVereD: maximum retries to deliver the message exceeded, can be

restarted by admin action

TBIT44 Adapters Ex1 RFC to WS

Page1 of 14

TBIT44 – Adapters Ex. 1 – RFC to WebService Overview

The purpose of this exercise is to implement a synchronous execution of a WebService using RFC from an R/3 system via XI. As a result of this exercise, you will become familiar with the basic sequence of steps to implement a simple interface with XI along with RFC sender adapter and SOAP receiver adapter. This exercise will also introduce you to browse, inspect and export WSDL for any remote enabled functions in a Web Application Server & import of WSDL

documents into integration repository.

Prerequisites

Basic knowledge of XI architecture.

Description

In the R/3 system (Sender) a remote enabled function module call is executed passing the user name as a parameter. The call is sent to XI (Request message), which maps the data, and executes a web service. The details about the user are then retuned to the caller. XI again maps the data (Response message) to match the format of the sender function.

For the purpose of this exercise, we will use client 821 of the XI system, to simulate a web service provider.

All remote enabled function modules in Web Application Server (6.20 & above) are available as webservices & the WSDL (Web Service Description Language) documents are available in the Web service repository at:

http://<host>:<port>/sap/bc/bsp/sap/webservicebrowser/search.html

We will use the function module Z_BAPI_USER_GET_DETAIL, exposed as a web service from the client 821 of the XI server.

BAPI_USER_GET_DETAIL SAP

R/3 4.6C Remote enabled _{function in SAP} WebAS exposed as a Webservice SOAP

RFC

TBIT44 Adapters Ex1 RFC to WS

Page2 of 14

Exercise steps

Step 1 – Preparation of the interfaces

1.1 Using your browser, open the following URL:

http://<host>:<port>/sap/bc/bsp/sap/webservicebrowser/search.html where <host> is the XI Server host, and <port> is the ICM port (can be obtained from transaction SMICM).

Hint: you may start from the TBIT40 Tools home page, to be found on the Integration Builder start page (via SXB_IFR), under Additional Information -> Tools for TBIT44.

1.2 Find the standard BAPI “BAPI_USER_GET_DETAIL”. By clicking on the wsdl link the WSDL is displayed in the browser. Save the WSDL locally as we will use this later to import it into the repository.

The webservice for BAPI_USER_GET_DETAIL will be invoked from R/3 system using an RFC. The input parameter for this webService is a user id (USERNAME) in the target system and it returns all the pertinent information about this userid. If an invalid Userid is entered, then a message “User xxxxx does not exist” is returned in table RETURN.

1.3 In the sender R/3 4.6C system (business system R3_BACKEND), you will create and use a remote enabled function module called Z_BAPI_USER_GET_DETAIL_## (where ## is your group number).

Go to transaction SE37 and enter BAPI_USER_GET_DETAIL. Copy this function to

Z_BAPI_USER_GET_DETAIL_## (## is your group number). Use function group ZATP.

In change mode, go to the “source code” tab and delete all executable lines of code. As a result we have a function module with no implementation logic, but with the exact same signature as BAPI_USER_GET_DETAIL (compare screenshot below).

TBIT44 Adapters Ex1 RFC to WS

Page3 of 14

Step 2 – Repository

*Please note, as a general rule, all development and configuration objects in XI are CASE-SENSITIVE.

2.1 From the Integration Builder home page, launch the Integration Repository. Log in with your user ID and password.

2.2 Please locate your Software Component (‘TBIT44_##’) and namespace

urn:sap-com:TBIT44:adapters:group## (## is your group number).

2.3 Open your SWCV and enable the import of RFC and IDoc interfaces from R/3, i.e. the system you created your function module in. Specify the connection information to the backend R/3 system as provided by the instructor.

TBIT44 Adapters Ex1 RFC to WS

Page4 of 14

2.4 In the left-hand frame, under your SWCV, click on “Imported objects” and click on “Import of SAP Objects.”

2.5 Log on to the Sender R/3 system (business system R3_BACKEND) and import the signature of your function module ‘Z_BAPI_USER_GET_DETAIL_##’. You have now imported the metadata for the calling RFC.

You may activate the imported objects now.

2.6 We will now import the web service metadata in the form of a WSDL file. In real-life this file would be supplied by the web service provider. For the purpose of this exercise, we will use the WSDL file previously saved.

2.6.1 Under your namespace in the left frame (urn:sap-com:TBIT44:adapters:group##), expand the node “Interface objects”.

2.6.2 Right click on External definitions and click on New. Create a new External Definition called ws_bapi_user_get_detail. Import the WSDL file saved previously. Make sure the Category is WSDL.

TBIT44 Adapters Ex1 RFC to WS

Page5 of 14

2.7 Create a new message interface.

2.7.1 In the left frame, right-click on the node “Message Interface” and select “New”. 2.7.2 The name of the message interface will be “ws_user_display_in”.

2.7.3 Make your interface “inbound” and “synchronous”. The input message type should reference the BAPI_USER_GET_DETAILInput from the external definitions and output message type should reference

BAPI_USER_GET_DETAILOutput, again from the external definitions. Save

the object.

2.8 Create the message mappings for the request and response.

2.8.1 Create a message mapping called ‘user_display_request_map’. This maps the record structure of the Z_BAPI_USER_GET_DETAIL_## to the record structure of the web service request.

TBIT44 Adapters Ex1 RFC to WS

Page6 of 14

2.8.2 Source message should be the Z_BAPI_USER_GET_DETAIL_## imported previously (to be found under Imported Objects).

Target message should be the BAPI_USER_GET_DETAILInput from the external WSDL definition (urn:sap-com:TBIT44:adapters:group##).

2.8.3 Since this is request mapping, we have to map only the USERNAME field. Save the object after mapping is done.

2.8.4 Create another message mapping named “user_display_response_map”. - Source message: BAPI_USER_GET_DETAILOutput from WSDL file.

- Target message: Z_BAPI_USER_GET_DETAIL_##.Response

2.8.5 Since all structure names are same, we can make use of a mapping feature where all fields and structures with identical names will get mapped

automatically. To do this, highlight the top nodes as shown below, and click on the icon at the top of the screen. All the nodes which have the same names will get automatically mapped. Save the object.

TBIT44 Adapters Ex1 RFC to WS

Page7 of 14

2.9 Now create an interface mapping.

2.9.1 Create a new interface mapping “user_display_in_map”.

2.9.2 Source interface: Z_BAPI_USER_GET_DETAIL_## (Imported Objects)

Target interface: ‘ws_user_display_in’ (namespace

urn:sap-com:TBIT44:adapters:group##). Make sure to pick the source and target

interfaces from your own SWCV and namespace.

2.9.3 Hit the refresh button below to populate the Source and Target messages. Notice that there is a request and response tab.

- Request message mapping: “user_display_request_map” - Response message mapping: “user_display_response_map”.

Save the object.

2.10 Finally, go to your change list and activate it. This concludes the steps required in Integration Builder Design.

TBIT44 Adapters Ex1 RFC to WS

Page8 of 14

Step 3 – Directory

3.1 From the Integration Builder home page, select “Integration Directory”.

3.2 Create your own scenario if you don’t have one already (“TBIT44_##”). Please make sure all the objects created below are added to this scenario.

3.3 Create a communication channel for the sender system:

3.3.1 The sender business system will be the R/3 system. Locate the business system ‘R3_BACKEND’ and assign it to your scenario.

3.3.2 Navigate to your scenario. Under the business system R3_BACKEND, create a communication channel called ‘RFC_sender_##’. A communication channel is essentially a physical connectivity to/from the application system. This is where the adapter configuration takes place.

3.3.3 Provide the following parameters:

- Adapter Type: RFC

- Sender

- Transport protocol: RFC

- Communication protocol: RFC (RFC-XML)

- Adapter Engine : Integration Server

3.3.4 For the RFC Server Parameters, provide the following values: - Application Server: <R/3 host name>

- Application Server Service: <gateway service name> (usually sapgw00) - ProgramID: ID_##_TBIT44 (where ## is your group number).

TBIT44 Adapters Ex1 RFC to WS

Page9 of 14

For the metadata repository server, provide connectivity and logon information to the R/3 system as well. This is the system from which the RFC adapter will retrieve the metadata in order to convert the RFC call into XML.

3.4 Create a communication channel for the receiver system:

3.4.1 The receiver Business System will be ‘Training’, which represents client 821 of the XI Server. Locate the Business System and assign it to your scenario. 3.4.2 In your scenario, under the Business System, create a new communication

channel ‘SOAP_receiver_##’.

- Adapter Type: SOAP

TBIT44 Adapters Ex1 RFC to WS

Page10 of 14

- Transport protocol: HTTP

- Message protocol: SOAP 1.1

- Adapter Engine : Integration Server

3.4.3 Under the connection parameters, provide the following:

- Target URL: this should be the URL of the Web Service listener (see

below). Make sure to specify client 821 at the end of the URL string. - Provide a valid user-id and password for client 821 of the XI server (you

may have to log in to the client via SAPGUI and change your password).

http://<host>:<ICM port>/sap/bc/soap/rfc/sap/BAPI_USER_GET_DETAIL?sap-client=821

3.5 Create a “Sender Agreement” object. This defines a binding between the sender communication channel and the outbound interface.

3.5.1 On the left frame, right-click on the “sender Agreement” Æ New. 3.5.2 Fill in the following values:

- Sender service: R3_BACKEND (BS for R/3 system)

- Interface (namespace):

Z_BAPI_USER_GET_DETAIL_##

(urn:sap-com:document:sap:rfc:functions)

- In the screen ‘edit sender agreement’, select your own communication channel ‘RFC_sender_##’.

3.6 Create a Receiver Determination object. 3.6.1 Specify the following parameters:

- Sender Service: Sender Business system (‘R3_BACKEND’). - Sender interface: Z_BAPI_USER_GET_DETAIL_##

(in namespace urn:sap-com:document:sap:rfc:functions) - Receiver Service: Receiver Business system (‘Training’).

TBIT44 Adapters Ex1 RFC to WS

Page11 of 14

3.7 Create an “Interface Determination”:

In the following steps, you will create an “Interface Determination” object. Now that we have defined a receiver for the message, we need to assign an inbound interface, and an interface mapping (if necessary).

3.7.1 Save your receiver determination object first. Then, in the area “Configuration Overview for Receiver Determination” at the bottom of your screen, hit refresh. 3.7.2 In the column “Receiver (Partner/Service)” right-click on “Not Defined” and

select “New Specific”, in order to create a new interface determination object. 3.7.3 You are now in the screen “Edit Interface Determination”. In the section

“Configured inbound interfaces” select the following using F4 help and select the inbound interface and mapping that you have created in your own SWCV and namespace. When you are done, please save the Interface Determination object.

- Inbound interface: ws_user_display_in

Namespace: urn:sap-com:TBIT44:adapters:group##

- Interface mapping: user_display_in_map

Namespace: urn:sap-com:TBIT44:adapters:group##

SWCV TBIT44_##

3.7.4 Go back to the main screen for your receiver determination. In the area

“Configuration Overview for Receiver Determination” at the bottom of the screen, hit “Refresh”.

3.7.5 In the column “Receiver Determination (Communication Channel)” right click on “Does not exist” and select “New Specific”. Here we have to create a receiver agreement. A receiver agreement defines a binding between the receiver communication channel and the inbound interface.

TBIT44 Adapters Ex1 RFC to WS

Page12 of 14

3.7.6 In the screen “Edit Receiver Agreement”, for the field “Receiver Communication Channel” use the input help (F4), and select your communication channel “SOAP_Receiver_##” (do not use Header Mapping).

3.7.7 Save the Receiver Agreement.

3.8 Go back to the main receiver determination screen and refresh. Your configuration is now complete. Go to change lists and activate your objects.

Step 4 – Testing

4.1 Log on to the sender system (R/3 backend, client 800) .

4.2 Create an RFC Destination: you will need to create your own RFC destination pointing to the registered program specified in the sender communication channel.

4.2.1 Create a new destination (‘TBIT44_DEST##’) of type T, using SM59.

4.2.2 Click on Registration button and provide the Program ID that was used in the creation of the RFC communication channel.

Note: the Program ID is case-sensitive and must match exactly what you specified in the sender RFC communication channel (‘ID_##_TBIT44’).

After saving your destination, you may use button “Test connection” to see if the destination works well with the registered RFC communication channel.

TBIT44 Adapters Ex1 RFC to WS

Page13 of 14

4.3 Test the function module call. In the R/3 backend, start transaction SE37 and input “Z_BAPI_USER_GET_DETAIL_##” for the Function Module name. Execute (F8). 4.4 As the RFC Target sys, provide your RFC destination (TBIT44_DEST##). Input any valid

TBIT44 Adapters Ex1 RFC to WS

Page14 of 14

4.5 Upon execution all the integration server steps will be carried out and a web service call using SOAP adapter should be made and the results will be displayed.

4.6 Inspection of payload: Log in to the integration server (XI client 800) and execute transaction

SXMB_MONI to monitor the processed XML messages.

4.7 Fill in the sender values appropriately so that you are looking at the messages you have processed, e.g. Sender Interface Name Z_BAPI_USER_GET_DETAIL_## for the request. 4.8 Inspect the request and the response message, in particular the payloads.

TBIT44 Adapters Ex2 File to JDBC

Page 1 of 10

TBIT44 – Adapters Ex. 2 – File to JDBC: Using Structure conversion and utilizing built-in EO processing in JDBC adapter

Overview

The purpose of this exercise is to implement an asynchronous scenario where a file adapter sends data in a comma delimited format; the file adapter performs structure conversion and converts contents of the file into XML format and sends to the integration engine. The data is then mapped to the jdbc XML SQL format and sent to the jdbc receiver.

As a result of this exercise, you will become familiar with configuring a file adapter to perform structure conversion and mapping the data to XML SQL format. The exercise also takes advantage of the built in Exactly Once (EO) processing capabilities of the JDBC adapter.

Exactly Once Processing - Background

As in the other adapters, Exactly Once messages are handled by default using status information in the J2EE server. All adapter error statuses and program terminations initialized externally are also handled in this mode. However, this does not include external program terminations during a database commit. In this case, the status of message processing is unclear since it can only be changed once the database commit has been completed.

The receiver JDBC adapter has two persistence modes that enable Exactly Once processing:

ƒ Local

ƒ Database

In the past, with the J2SE Adapter Engine, Local meant that EO handling was file based (i.e. status information management was maintained within the local file system). This caused security concerns and was generally considered unsafe. In Database mode, message processing and status information management took place in the same database allowing the processing steps to have the same commit cycle and eliminating any doubt in EO handling. With XI 3.0, since the J2EE Adapter Engine is deployed on top of the J2EE engine (which also has database persistence) the EO handling in Local mode is now also database based and in one database transaction with the message processing including the message persistence. This makes the Local mode EO handling just as reliable as Database mode EO handling.

Note: Currently, the Database mode has not been implemented. It will be enabled for SP9. Prerequisites

Basic knowledge of XI architecture & databases.

Description

A table VendorMaster in the SQL server is created as shown: In this table we will store the vendor data.

File system

JDBC File

TBIT44 Adapters Ex2 File to JDBC

Page 2 of 10

Exercise steps

*Please note, as a general rule, all development and configuration objects in XI are CASE-SENSITIVE.

Step 1 – SLD:

Creating a technical system, business system and the software component version are not in scope for this exercise.

Step 2 – Repository

2.1 Log on to the Integration Repository.

2.2 Examine existing data types: under the SWCV ‘TBIT44_BASE_COMP’ (or in your SWCV under Basis Objects), namespace ‘urn:sap-com:TBIT44:adapters:common’, expand the node Data types. Please inspect the data types Vendor_file_DT &

Vendor_SQL_DT. Please pay special attention to Vendor_SQL_DT. Data type

Vendor_file_DT is used to describe the data sent by the file & Vendor_SQL_DT is used

to describe the data in XML sql format. We will be using this format to write to the database using JDBC adapter.

2.3 Examine existing message types: Vendor_file and Vendor_SQL.

2.4 Create message interfaces: create 2 new message interfaces in your SWCV TBIT44_## in your namespace urn:sap-com:TBIT44:adapters:group##:

- Vendor_file_out_## (outbound asynchronous) using the message type Vendor_file.

- Vendor_SQL_in_## (inbound asynchronous) using the message type Vendor_SQL.