File Adapter

Author: Dennis Kropp

Objectives
After completing this session, you will be able to:

Understand the basics of J2EE file adapter

Understand how to configure sender & receiver
file adapter
Use structure conversion with sender file adapter
Be familiar with technical aspects of the file
adapter

SAP AG 2004, File Adapter, Dennis Kropp, 2

File Adapter

Type File
Exactly one sender
agreement per
Communication
channel
At least interface name
and sender service
must be qualified in the
sender agreement

SAP AG 2004, File Adapter, Dennis Kropp, 3

The file adapter is used to read and write files at the OS level. The OS-level
directory must be accessible by the service user of the Adapter engine, with the
appropriate read/write permissions.
The file adapter can also act as an FTP client, meaning that it can perform GET
and PUT in the sender and receiver case, respectively.

File Adapter: Sender

SAP AG 2004, File Adapter, Dennis Kropp, 4

File Adapter: Sender

File System Access Parameters:

Source Directory and Filename
File Type

Text ( e.g for XML files ) OR

Binary

SAP AG 2004, File Adapter, Dennis Kropp, 5

File Adapter: Sender

File Processing Parameters:

Quality of Service

Best Effort

EO

EOIO Specify Queue name in this case

Poll Interval
Processing Mode

Archive w.timestamp possible

Set to Read only

Delete

Test

Processing Sequence
Operating system command
SAP AG 2004, File Adapter, Dennis Kropp, 6

When a queue name is specified, it gets created in XI automatically.

Specifying File content Conversion

Required to convert non-xml file (flat) to XMB (xml) file

or Vice-Versa.

SAP AG 2004, File Adapter, Dennis Kropp, 7

File Adapter Receiver

File System Access Parameters:

Target Directory
File Name Schema
File Construction Mode
z Create
z Append
z Add Timestamp
z Add MessageID
z Add Counter

SAP AG 2004, File Adapter, Dennis Kropp, 8

The target directory is created if one does not exist.

Message ID is from XI.
Time stamp has a yyyyMMdd-HHmmss-SSS format.
The quality of service is inherited from the Integration Server (in the case of a file,
only QoS EO or EOIO makes sense, since the communication cannot be
synchronous).

File Adapter Receiver

Parameters Continued
File Type
z Text
z Binary

File Encoding

SAP AG 2004, File Adapter, Dennis Kropp, 9

Example1 csv file conversion - simple structure

The following screens demonstrate the conversion of a

csv (flatfile) file into an XML structure that can be used
within XI

File adapter channel picks up csv file and create xml

structure as configured in channel
after that all XI operations, e.g. mapping are possible
with this structure
for more detailed information on structure
conversion see XI30 documentation

SAP AG 2004, File Adapter, Dennis Kropp, 10

! Note that due to an issue within XI structure creation the execution

of a mapping program fails with a runtime exception, even if it seems
that source structure is ok. This is caused by missing message type
prefix (ns) This should be fixed in SP04 (FeaturePack)

10

Source structure
Source structure of csv file:

Adams,James,P,ABC Co.,29 Frankford Rd,Bloomington,IL,60525,708,3525555

Miller,Maria,B,Conrad Corp,1234 Smith St,Buffalo Grove,CA,60089,708,3334567
Smith,Fred,A,Sand Inc.,Beach Street,Pismo Beach,FL,33321,407,8123456
Veldin,Beth,M,Any Co.,697 Berry Road,Highland Park,IL,60012,708,4445987
Jones,Mary,,McCormick Enterprises,777 Lincoln Drive,Maryland,CA,19444,415,6666666

SAP AG 2004, File Adapter, Dennis Kropp, 11

Represents source structure that has to be converted into XML

11

IB Directory channel configuration

SAP AG 2004, File Adapter, Dennis Kropp, 12

Choose file content conversion as message protocol as shown

Document name represents message type, document namespace is XML
namespace of document
Recordset name creates root node of document that consists of recordset
structure
Record set structure defines the structure of record set and number of each
substructure. E.g. in this example for each record set ContactFile ONE structure
named Contact is created
Field Separator value defines which character (or space) separates the different
fields of source
End separator defines end of one structure -> nl = newLine
Optional value defines optional fields of structure. E.g. middle field is optional in
example

12

XML structure after conversion

<?xml version="1.0" encoding="UTF-8"?>
<MT_ContactFile xmlns="http://sap.com/xi/Performance">
<ContactFile>
<Contact>
<lastName>Adams</lastName>
<name>James</name>
<middle>P</middle>
<company>ABC Co.</company>
<street>29 Frankford Rd</street>
<city>Bloomington</city>
<BL>IL</BL>
<zip>60525</zip>
<dept>708</dept>
<phone>3525555</phone>
</Contact>
</ContactFile>
<ContactFile>
<Contact>
<lastName>Miller</lastName>
<name>Maria</name>
<middle>B</middle>
<company>Conrad Corp</company>
<street>1234 Smith St</street>
<city>Buffalo Grove</city>
<BL>CA</BL>
<zip>60089</zip>
<dept>708</dept>
<phone>3334567</phone>
</Contact>
</ContactFile>
.....
SAP AG 2004, File Adapter, Dennis Kropp, 13

each recordset Input contains one substructure prefix, multiple substructures

main and one substructure

check

13

XML structure after conversion

<?xml version="1.0" encoding="utf-8"?>
<MT_ContactFile xmlns="http://sap.com/xi/Performance">
<ContactFile>
<Contact>
<lastName>Adams</lastName>
<name>James</name>
<middle>P</middle>
<company>ABC Co.</company>
<street>29 Frankford Rd</street>
<city>Bloomington</city>
<BL>IL</BL>
<zip>60525</zip>
<dept>708</dept>
<phone>3525555</phone>
</Contact>
<Contact>
<lastName>Miller</lastName>
<name>Maria</name>
<middle>B</middle>
<company>Conrad Corp</company>
<street>1234 Smith St</street>
<city>Buffalo Grove</city>
<BL>CA</BL>
<zip>60089</zip>
<dept>708</dept>
<phone>3334567</phone>
</Contact>
.........
</ContactFile>
SAP AG 2004, File Adapter, Dennis Kropp, 14

Record set structure: Contact,*

Now the record set contains all substructures Contact in one record set

14

Example2 csv file conversion - advanced structure

following screens demonstrate conversion of a csv (flatfile) file
into a XML structure that can be used within XI
File adapter channel picks up csv file and create xml structure
as configured in channel
Note that you need a sender agreement to send files by file
adapter
each file sender channel can only be used in one sender
agreement
all XI operations, e.g. mapping, context based routing etc, are
possible with this structure
for more detailed information on structure conversion see XI30
documentation

SAP AG 2004, File Adapter, Dennis Kropp, 15

! Note that due to an issue within XI structure creation the execution

of a mapping program fails with a runtime exception,
even if it seems that source structure is ok. This is caused by missing message
type prefix
(ns) This should be fixed in SP04 (FeaturePack)

15

Source structure
1London20.04.2004
2DAR
11000000123456,0012345678901111SalesAcc
2WECHS 13000000123456,0012345678901111Collection
2DAR
11000000123456,0012345678901111SalesAcc
2DAR
11000000123456,0012345678901111SalesAcc
2DAR
11000000123456,0012345678901111SalesAcc
2WECHS 13000000123456,0012345678901111Collection
2KK
20009999999999,9909876543219999DepositMoney
2DAR
11000000123456,0012345678901111SalesAcc
2DAR
11000000123456,0012345678901111SalesAcc
2DAR
11000000123456,0012345678901111SalesAcc
2DAR
11000000123456,0012345678901111SalesAcc
2DAR
11000000123456,0012345678901111SalesAcc
2WECHS 13000000123456,0012345678901111Collection
2KK
20009999999999,9909876543219999DepositMoney
2DAR
11000000123456,0012345678901111SalesAcc
2DAR
11000000123456,0012345678901111SalesAcc
2DAR
11000000123456,0012345678901111SalesAcc
2DAR
11000000123456,0012345678901111SalesAcc
2DAR
11000000123456,0012345678901111SalesAcc
2WECHS 13000000123456,0012345678901111Collection
2KK
20009999999999,9909876543219999DepositMoney

2KK
20009999999999,9909876543219999DepositMoney
300000000001234565432,2200000000001234565432,33
SAP AG 2004, File Adapter, Dennis Kropp, 16

Represents source structure that has to be converted into XML

16

IB Directory channel configuration (1)

SAP AG 2004, File Adapter, Dennis Kropp, 17

Choose file content conversion as message protocol as shown

Document name represents message type, document namespace is XML
namespace of document
Recordset name creates root node of document that consists of recordset
structure
Recordset structure defines the structure of record set and number of each
substructure. E.g. in this example for each record set Input a (sub-)structure
prefix, occurs one time ; main, occurs unbounded and ckeck, occurs one time
, will be

created

1 recordset will be send per message

Key field name defines a field in source file that value identifies each substructure

17

IB Directory channel configuration (2)

SAP AG 2004, File Adapter, Dennis Kropp, 18

In this structure, fields with fixed length are used , the value defines the length of
each field
FieldNames defines the name of each field in structure
A keyfield is needed to identify the start of a new substructure, here the keyfield is
KZ
It means if KZ = 1 then the rules for prefix were used, if KZ=2 then main etc..
keyFieldInStructure defines whether the keyfield occurs in the target structure or
not, ignore means it does not appear

18

XML structure after conversion

<?xml version="1.0" encoding="utf-8"?>
<MT_Input xmlns="http://sap.com/xi/Mappingtest">
<Input>
<prefix>
<agency>London</agency>
<date>20.04.2004</date>
</prefix>
<main>
<product>DAR</product>
<contract>1100</contract>
<total>0000123456,00</total>
<GPnum>1234567890</GPnum>
<GPnumAdv>1111</GPnumAdv>
<description>SalesAcc</description>
</main>
<main>
<product>WECHS</product>
<contract>1300</contract>
<total>0000123456,00</total>
<GPnum>1234567890</GPnum>
<GPnumAdv>1111</GPnumAdv>
<description>Collection</description>
</main>

<check>
<checkSum1>00000000001234565432,22</checkSum1>
<checkSum2>00000000001234565432,33</checkSum2>
</check>
</Input>
</MT_Input>
SAP AG 2004, File Adapter, Dennis Kropp, 19

19

 each recordset Input contains one substructure prefix, multiple substructures main and one
substructure

check

<?xml version="1.0" encoding="utf-8"?>

<MT_Input xmlns="http://sap.com/xi/Mappingtest">
<Input>

<prefix>

<agency>London</agency>

<date>20.04.2004</date>

</prefix>

<main>

<product>DAR</product>

<contract>1100</contract>

<total>0000123456,00</total>

<GPnum>1234567890</GPnum>

<GPnumAdv>1111</GPnumAdv>

<description>SalesAcc</description>

</main>

<main>

<product>WECHS</product>

<contract>1300</contract>

<total>0000123456,00</total>

<GPnum>1234567890</GPnum>

<GPnumAdv>1111</GPnumAdv>

<description>Collection</description>

</main>

<main>

<product>KK</product>

<contract>2000</contract>

<total>9999999999,99</total>

<GPnum>0987654321</GPnum>

<GPnumAdv>9999</GPnumAdv>

<description>DepositMoney</description>

</main>

<check>

<checkSum1>00000000001234565432,22</checkSum1>

<checkSum2>00000000001234565432,33</checkSum2>

</check>

</Input>
</MT_Input>

20

Summary

Now you should be able to:

Understand the basics of J2EE file adapter

Understand how to configure sender & receiver
file adapter
Use structure conversion with sender file adatper
Be familiar with technical aspects of the file
adapter

SAP AG 2004, File Adapter, Dennis Kropp, 21

21