Exercise 1: File sender to IDoc

Overview

The purpose of this exercise is to implement a simple one-way, asynchronous link between a file
sender and the R/3 system, using XI. As a result of this exercise, you will become familiar with the
basic sequence of steps to implement a simple interface with XI. You will be able to understand
the structure of objects in the SLD, Integration Repository and Integration Directory. This exercise
will also introduce the graphical mapping environment, the central J2EE adapter engine, the file
adapter for sender systems and the IDoc adapter.

SAP IDo
c File Legacy System
R/3 4.6C
XML Vendor Data
CREMAS03

Prerequisites

Basic knowledge of XI architecture

Description

A custom XML document containing vendor information is picked up from the file system by the
file adapter. The message is mapped to IDoc-XML format and then routed to the IDoc adapter.
The CREMAS IDoc (vendor master data) is posted into the backend R/3 system. A vendor will be
created by the R/3 application.

Exercise steps

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

Step 1 SLD

Since this is the first exercise, we have to define a software component which will house all our
development objects. This is done in the system landscape directory (SLD). We will also define a
technical system and business system for the third party application which is sending the file.

1.1 Create software component.

1.1.1 Log in to the Integration Server client via SAPGui and change your password.

1.1.2 From the main menu select Start Integration Builder (transaction SXMB_IFR). This will
launch the Integration Builder homepage in a separate window.
1.1.3 In the Integration Builder home page, select System Landscape Directory. This will
bring up the SLD in a separate window (note the URL shortcut /sld).

1.1.4 Select software catalog. The list of all products appears. Browse around the list and
inspect specific product versions by clicking on them. The details page will show you
which software components are exposed for a given product.

You can go back to the main page by clicking back to Software Catalog.

1.1.5 When you are finished browsing, from the software catalog screen select Software
Component from the drop-down list.

1.1.6 Select New Component. This will take you to the wizard for creating a new Software
Component (SWC).

1.1.7 The product we will use is called XI RIG US Workshop of vendor SAP XI RIG US.
Select this product from the drop-down list. Fill out the remaining fields as specified
below. Then click Create. Note: after the SWC is created, you will see a confirmation
 message in a green box at the top of the screen. The fields of the wizard will be reset in
order to allow you to create another SWC if necessary. Click Cancel to get out of the
wizard.

Vendor: SAP XI RIG US

Name: XI RIG US workshop XX (replace XX with your group number).
Version: 1.0

1.2 Create technical system

1.2.1 Go to the SLD homepage (click home in the upper left corner.)

1.2.2 Choose Technical landscape. In the technical system browser, select technical system
type: third-party.

1.2.3 Select New Technical System. This will take you to the wizard.

1.2.4 For the type of technical system, select Third-Party. Click Next>

1.2.5 System Name: XIWS_legacy_TS_XX (replace XX with your group number).

Host Name: <your host name>.
Click Next.

1.2.6 From the list of available products, select XI RIG US Workshop, 1.0 then click Add.
The product will appear in the Selected Products list. Verify that the software
component you created in the previous step is present and is checked. Click Finish.
1.2.7 Verify in the technical system browser that the newly created object appears in the list
under TS type: third-party.

1.3 Create Business System

1.3.1 In the SLD homepage, select Business Landscape.

1.3.2 Select New business system. This will take you to the wizard.

1.3.3 For the business system name, enter XIWS_legacy_BS_XX (replace XX with your group
number). Click Next.

1.3.4 As technical system type, select third-party.

1.3.5 Select your technical system

1.3.6 As logical system name, enter WS[XX] (replace XX with your group number). This will
be the ALE name of the business system.

1.3.7 In the next screen, verify that product and software component are correct. Make sure
your SWC is checked.
1.3.8 Finally, make sure that this business system is identified as an application system (as
opposed to an integration server). Choose the appropriate related integration server from
the drop-down list. Click Finish.

Step 2 Repository

2.1 From the Integration Builder home page, select Integration Repository. This will launch
the Java Web Start application. Log in with your user ID and password.

2.2 In the left-hand frame, find the software component XI RIG US workshop base comp
and expand it. In the section imported objects you will find the IDoc
CREMAS.CREMAS03. Double-click on it and inspect the IDoc metadata.

2.3 From the tools menu, select Import from system landscape directory import
software component versions.

2.4 From the list of software component versions, select your own software component
created in step 1 (XI RIG US workshop XX). Click Import.

2.5 The newly created SWC should appear in the left frame. Open the SWC and then
double-click on the version. This will bring up the SWC version screen in the right frame.

2.6 Switch to edit mode and add a namespace (urn:xiworkshop:group[XX]:legacy) to this

SWC. Replace XX with your group number. Save and close. The new namespace should
be visible under the SWC version node in the left frame.

2.7 Under your namespace in the left frame, expand the node Interface objects.

2.8 Create new data types.

2.8.1 Right-click on Data types and select New. First we will create a data type called
Address_DT.

2.8.2 In the data type editor, create a structure for the Address, as specified below. Save the
object.

2.8.3 Now create another data type called Vendor_DT. Its structure should be as follows:

Note that the Address_DT type previously created is now referenced from the main data type.
This is called nesting of datatypes. This is achieved by selecting Search Help from the drop-
down menu in the Type column. There you will be able to select any existing data type in the
same SWC.

2.9 Create a new message type

2.9.1 In the left frame, right-click on the node Message Types and select New.
2.9.2 The name of the message type will be Vendor. Please note that the root element of the
XML business document needs to match the message type exactly (case-sensitive).

2.9.3 For the section data type used you can go to the input help (F4) and choose your data
type (Vendor_DT) from there. As an alternative you can also drag and drop the data type
from the left frame. Make sure that the namespace is filled in correctly. Save the object.

2.10 Create a Message Interface object (from the left frame), called Vendor_out. The
interface should be outbound and asynchronous. It should reference your message type
(drag and drop or use F4 help).

2.11 Now we will create a graphical mapping between the custom XML message and the
IDoc. Note: The complete mapping rules are available at the end of this document. In the
left frame, close the section Interface objects and expand mapping objects. Create a
Message Mapping object and name it Vendor_CREMAS03. You are now in the
graphical mapping editor. The source message is on the left, the target message on the
right, and the mapping rules at the bottom.

2.11.1 As source message, select your message type Vendor. You can choose Search for
Repository object. Make sure that you select your own SWC. There you will be able to
find your namespace and message type. Alternatively, you can drag and drop your
message type onto this area of the screen.

2.11.2 As target message, select the CREMAS.CREMAS03 IDoc. As a reminder, you can find
the IDoc under SWC XI RIG US workshop base comp Imported objects.

2.11.3 Now that we have defined the source and target message, we can start defining the
mapping rules. Note: in order to get a larger working area, you can detach the window by
clicking on the thumbnail in the upper right corner.

2.11.4 Map the fields of the source document to the equivalent fields in the IDoc. This can be
achieved easily by locating the target field in the IDoc structure and then drag-and-drop
from the source field to target field. Please refer to the table below for the mapping rules
(segments and fields are sorted according to their order of appearance in the IDoc).

Source field in Vendor Target field in CREMAS03

VendorNumber E1LFA1M LIFNR

Address Country E1LFA1M LAND1
LastName E1LFA1M NAME1
Address City E1LFA1M ORT01
Address Zip E1LFA1M PSTLZ
SearchTerm E1LFA1M SORTL
Address Street E1LFA1M STRAS

VendorNumber E1LFA1M E1LFB1M LIFNR

VendorNumber E1LFA1M E1LFM1M LIFNR

Currency E1LFA1M E1LFM1M WAERS
2.11.5 Now we have to assign constants to certain fields and attributes in the IDoc (for segment
qualifiers, hardcoded values and XML attributes). This can be achieved by following the
procedure below. Refer to the table below for more details on the mapping rules.

2.11.5.1Double-click on the target field in the IDoc.

2.11.5.2At the bottom of the screen, select Constants from the drop-down list for function type.
2.11.5.3Click on the function Constant. Now the empty constant appears in the screen.
2.11.5.4Double-click on the empty constant and assign a specific value.
2.11.5.5Connect the constant to the target field.

Constant Target field in CREMAS

1 CREMAS03 IDOC BEGIN

1 E1LFA1M SEGMENT
009 E1LFA1M MSGFN
COMPANY E1LFA1M ANRED
LIEF E1LFA1M KTOKK

1 E1LFA1M E1LFB1M SEGMENT

009 E1LFA1M E1LFB1M MSGFN
3000 E1LFA1M E1LFB1M BUKRS
31000 E1LFA1M E1LFB1M AKONT
A1 E1LFA1M E1LFB1M FDGRV

1 E1LFA1M E1LFM1M SEGMENT

009 E1LFA1M E1LFM1M MSGFN
3000 E1LFA1M E1LFM1M EKORG

2.11.6 For the segments E1LFB1M and E1LFM1M please assign an empty constant. This is
necessary because these segments are optional in the IDoc. Although some underlying
fields have already been mapped, If the parent node is not explicitely used as the target
of a mapping, the segment will not be instantiated at all.

2.11.7 Finally, right-click on the segment EDI_DC40 and disable it (this segment is mandatory
but will be filled out automatically by the IDoc adapter. Save your mapping.

2.11.8 Now you can test your mapping by selecting the test tab. Select Generate instance.
2.11.9 Fill in the following values in the XML instance and click execute mapping . In the
right-hand side you should see the IDoc populated with the appropriate values. Note that
all optional segments and fields of the IDoc, that were not expliitely mapped, were not
generated.

VendorNumber Use the vendor number specified in the exercises

overview (Verify with the instructor!)
LastName <Your choice>
SearchTerm <Your choice>
Currency USD
Address Street <Your choice>
Address City <Your choice>
Address Zip <Your choice>
Address Country US

2.11.10 Save the source XML instance to your desktop. This is the document which you will use
later on for testing.
2.11.10.1 Select Source document view
2.11.10.2 Highlight the entire XML document
2.11.10.3 Copy and paste to a file on your PC: VendorXX.xml
2.12 Now create an object of type Interface mapping, named Vendor_out_CREMAS03.
Assign the following references:
- Source interface: Vendor_out (your outbound interface)
- Target interface: CREMAS.CREMAS03 (the IDoc from the base SWC)
- Mapping program: Vendor_CREMAS03 (your message mapping)

2.13 Finally, in the left-hand frame, go to your change list and activate it.

Step 3 Directory

3.1 From the Integration Builder home page, select Integration Directory

3.2 The first step is to create a scenario object. This will serve as container for all your
configuration work in the following exercises. Create a new scenario called
xiworkshop_group[XX].

3.3 Expand Service without party and right-click on Business System Assign Business
System.

3.4 In the wizard, leave the Party name blank and then select your own business system
(XIWS_legacy_BS_XX). Uncheck the box Create Communication Channels
Automatically. This service (business system) represents the legacy system which will
be sending data as XML files.

3.5 Now create a communication channel. The communication channel is essentially the
physical connectivity to/from the application system. This is where the adapter
configuration takes place. In this case we need to configure the file adapter to poll for
new files and send them to the Integration Server.
3.5.1 Expand your service and right-click on communication channel New. Name your
communication channel File_sender.

3.5.2 For the adapter type, use the F4 help and select File.
3.5.3 Specify Sender since the adapter will be sending messages to the IS.
3.5.4 Specify the following parameters:
- Transport Protocol: File System (NFS) (NFS or FTP could be used).
- Message Protocol: File (you can process the file as-is, or convert a flat file to XML.
- Adapter Engine: Integration Server (you can use the central or decentral AE).
3.5.5 For the File System Access Parameters, enter the following:
- Source Directory: D:/workshop/group[XX] (this is your shared directory on the server)
- File Name: Vendor[XX].xml
3.5.5 Select File Type binary.
3.5.6 Enter the following processing parameters:
- Quality of service: Exactly Once
- Poll Interval (secs): 600000 (please use a very high poll interval for test/training
purposes).
 - Processing mode: delete (the file will be deleted after being processed).
3.5.7 The sender file adapter is now configured. Save your communication channel.

3.6 The next step is to create a Sender Agreement object. This defines a binding between
the communication channel you just created, and the outbound interface.
3.6.1 In the left frame, right-click on Sender Agreement New.
3.6.2 Select your service (no party).
3.6.3 Select your interface (Vendor_out). Make sure that the correct namespace is utilized.
3.6.4 In the screen Edit Sender Agreement, use F4 help for the Sender Communication
Channel field. Select your communication channel (File_sender). Save and close.

3.7 From the left frame, create a new Receiver Determination object. This is the main part
of the routing process, where you assign a receiver for your message.
3.7.1 Select your sender service and interface

3.7.2 In the Configured Receivers area, choose the existing service for the target R/3 system
(M13_800). Save your receiver determination.

3.8 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.8.1 In the area Configuration Overview for Receiver Determination at the bottom of your
screen, hit refresh.
3.8.2 In the column Receiver (Partner/Service) right-click and select New Specific, in order
to create a new interface determination object.
3.8.3 You are now in the screen Edit Interface Determination. In the section Configured
inbound interfaces select the following using F4 help. When you are done, please save
the Interface Determination object.
- Inbound interface: CREMAS.CREMAS03
- Interface mapping: Vendor_out_CREMAS03
3.9 Finally you will create a Receiver Agreement object. This will allow you to assign a
receiver communication channel to the receiver service/interface you have chosen.
3.9.1 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.9.2 In the column Receiver Determination (Communication Channel) right click and select
New Specific.
3.9.3 In the screen Edit Receiver Agreement, for the field Receiver Communication Channel
use the input help (F4), and select the communication channel XIWS_IDoc_receiver.
This is a predefined channel which is used for all inbound IDocs into the R/3 system.
Save the Receiver Agreement.

3.10 Go back to the main receiver determination screen and refresh. Now your configuration is
complete. Before activating the objects we need to set up the input file in the next step
(indeed, as soon as your sender communication channel is activated, the polling
sequence of the file adapter will start immediately).

Step 4 Testing

4.1 Find the file Vendor[XX].xml which you had previously saved, and copy it to your shared
folder under \\<hostname>\workshop\group[XX]. Please note, the name of the file should
match exactly what you have specified in your sender communication channel.

4.2 Now you can go back to the Integration Directory, open your change list and activate your
objects.

4.3 It will take a few seconds for the cache refresh to take place, and for your changes to be
propagated to the Adapter Engine. Please ignore any message box that you may receive
subsequently. This has to do with the propagation of configuration changes to some decentral
adapter engines which are not in use.

4.4 Monitor your directory. After a few seconds your file VendorXX.xml should disappear. This
means that the file adapter has successfully processed it and the file was deleted.

4.5 In SAPGui, choose monitoring Integration Engine monitoring (transaction SXMB_MONI).

4.6 Choose monitor for processed XML messages. You can filter using different criteria, for
example by date and also by sender service (find your own business service name in the
drop-down list). In the monitor, your message should appear with a checkered flag (message
processed successfully). From there you can also navigate to the IDoc adapter.

4.7 In the backend R/3 system, go to transaction WE05 and search for IDocs according to the
logical system name used by your sender. Verify that your IDoc was posted. If everything
goes well, the IDoc should have status 53 (application document posted). If you expand the
status record you will see the vendor number that was created. Write down the vendor
number for future reference.

4.8 Check in transaction MK03 that your vendor was created.

 Appendix: naming conventions and terminology

Exercise 1

Area Obj. type Object name Description

SLD TS XIWS_legacy_TS_XX[00..30] Technical system for legacy app
BS XIWS_legacy_BS_XX[00.30] Business system for legacy app
Log.Sys. XIWS_XX Logical system name for BS
SWC XI RIG US workshop [00..30] Individual SWC for exercises
Int. Rep. NS urn:xiworkshop:groupXX[00..30]:legacy Namespace for legacy objects
Data type Vendor_DT Vendor data type
Address_DT Nested DT
Msg.type Vendor Vendor message type
Msg.int. Vendor_out Message interface
Msg.map Vendor_CREMAS03 Message mapping
Int.map Vendor_out_CREMAS03 Interface mapping
Int. Dir scenario xiworkshop_groupXX[00..30] Common for all exercises
service XIWS_legacy_BS_XX[00..30] Derived from BS (no party)
Send c.c. File_sender Sender comm. channel
Rec. c.c. XIWS_IDoc_receiver Receiver c.c. used for workshop
R/3 IDoc CREMAS.CREMAS03 Vendor master data
Log.Sys. WSXX[00..30] Same as above
File sys folder \\hostname\workshop\groupXX[00..30] D:\workshop\groupXX[00..30]
Transformation rules for Vendor CREMAS03 mapping (constants are highlighted).

Source field in Vendor Target field in CREMAS03

1 CREMAS03 IDOC BEGIN

1 E1LFA1M SEGMENT
009 E1LFA1M MSGFN
VendorNumber E1LFA1M LIFNR
COMPANY E1LFA1M ANRED
LIEF E1LFA1M KTOKK
Address Country E1LFA1M LAND1
LastName E1LFA1M NAME1
Address City E1LFA1M ORT01
Address Zip E1LFA1M PSTLZ
SearchTerm E1LFA1M SORTL
Address Street E1LFA1M STRAS

1 E1LFA1M E1LFB1M SEGMENT

009 E1LFA1M E1LFB1M MSGFN
VendorNumber E1LFA1M E1LFB1M LIFNR
3000 E1LFA1M E1LFB1M BUKRS
31000 E1LFA1M E1LFB1M AKONT
A1 E1LFA1M E1LFB1M FDGRV

1 E1LFA1M E1LFM1M SEGMENT

009 E1LFA1M E1LFM1M MSGFN
VendorNumber E1LFA1M E1LFM1M LIFNR
3000 E1LFA1M E1LFM1M EKORG
Currency E1LFA1M E1LFM1M WAERS