Configuring a Sender File Adapter

Objective

After completing this lesson, you will be able to configure the sender file adapter

Sender File Adapter

The sender file/File Transfer Process (FTP) adapter can read files and send them to message processing. To do this, the file adapter needs information about the structure, name, and directory of the file to be processed, and information for processing on the Integration Server. Consequently, a file adapter must be configured for every scenario.

The sender file/FTP adapter performs the following tasks:

  • The adapter searches the specified directory for files based on the time interval setup in the communication channel definition.
  • The adapter reads the file and uses structure information of the file to generate an XML message that the Integration Server can process.

Design Structure in the Enterprise Services Repository

A third-party software component provides data and writes it to a file. The structure of the data in the file is determined by the outbound interface of the software component. Ideally, you want to evaluate this file directly and transfer it to SAP Process Integration (PI) without converting it into another data format. Therefore, the structure of the data can be mapped as a message type in the Enterprise Services Repository (ESR) and used as an outbound service interface.

​You create a data type in the ESR for each line type in the file. The whole structure is then referenced in a message type. Create an outbound service interface for each outbound interface. This outbound service interface references a message type and contains information about whether the interface is synchronous or asynchronous. The structure of the objects depends on the exact file structure.

The Integrated Configuration specifies the name of the service interface and the namespace where the service interface was created and sends this information for processing.

Sender File Adapter Configuration

The sender file/FTP adapter is part of an Advanced Adapter Engine (AAE) and you configure it in a communication channel in the ID.

Hint

The data structure and possibly the names that you want to use, or the file and the directory can differ for each outbound interface. Therefore, configure a separate communication channel for each interface.

The configured communication channel is referenced in the inbound processing part of the integrated configuration that represents the connection between the interface and the sender system.

When you have created a communication channel for the sender system (business system or component), choose File from the input help as the adapter type and specify Sender as the type.

Values on the Parameters Tab Page

On the Parameters tab page, you can choose between several values. These are described in the following table.

Values on the Parameters Tab Page

Field NameValue
Transport ProtocolNFS or FTP
Message ProtocolFile or File Content Conversion
Adapter EngineCentral or Non-Central

If you select Network File System (NFS), specify the source directory and file name.

If you select FTP, specify the FTP connection parameters (for example, server, port, user, and so on).

After you choose the values on the Parameters tab page, specify the settings for the following parameters of the file:

  • Quality of service (QoS)

    The QoS determines whether the message is processed synchronously Best Effort (BE), or asynchronously Exactly Once (EO), or Exactly Once In Order (EOIO).

  • Poll Interval (seconds)

    The poll interval determines the time interval in which the system checks the directory specified in the adapter configuration for a file.

You can also select the Msecs to Wait Before Modification Check checkbox to enter the number of milliseconds that the adapter must wait before it checks whether the files have been changed. This check prevents files that are still being created by the sender system from being read.

Message Protocol: File Content Conversion

If you select Message Protocol: File Content Conversion, you can convert a plain text file into the SAP PI XML format.

The required configuration parameters are first explained with the help of a simple example; the individual parameters are described individually at the end of the lesson.

Format of the Information Transferred After the XML File is Converted

The format of the information that is transferred after the XML file gets converted into a text file is as follows:

Code Snippet
123
value1, value2
value3, value4
...

Design Time

You must create a message type that references a complex data type in the ESR.

Simple Message Type DemoMsgType1

NameCategoryTypeOccurrence
DemoMsgType1N/ADT_Demo1N/A
-Struc1ElementDT_Simple11...unbounded
- field1Elementxsd:string1
- field2Elementxsd:string1

The simple data type DT_Simple1 has two fields. It is referenced by a data type DT_Demo1 that, in turn, is referenced in message type DemoMsgType1.

Hint

The names can be predefined by the sender system and do no need to be part of the file. They can be of your choice. However, during the communication channel configuration process, the names of the message type, structures, and fields are specified and must match the information in the ESR.

Configuration Time

Specify the name and namespace of the message type (under Document) in the section for content conversion parameters. The message type is used as the root element.

Specify the name of the structure (Struc1) as the Recordset Name and specify the field separator as Struc1.fieldSeparator.

Content Conversion Parameters

NameValue
Document NameDemoMsgType1
Document NamespaceUrn:educationsap.com/bit/demo
Recordset NameStruct1
Recordset StructureStruct1,*
Strct1.fieldSeparator,
Struct1.fieldNamesfield1, field2
ignoreRecordsetNametrue

Because Struc1 can occur unlimited times, the recordset structure shows Struc1 with unlimited occurrence (*). The names of the fields are listed in the parameter Struc1.fieldNames.

Hint

To prevent the structure Struc1 from being listed more than once, the parameter ignoreRecordset has been set to true. See SAP Note 791737.

Result for a Simple XML Structure

The following code illustrates an example result for a simple XML structure:

Code Snippet
12345678910
<ns:DemoMsgType1 xmlns:ns="urn:educationsap.com/bit/demo">
<Struc1>
 <field1>value1</field1>
 <field2>value2</field2>
</Struc1>
<Struc1>
 <field1>value3</field1>
 <field2>value4</field2>
</Struc1>
</ns:DemoMsgType1>

Different Structures

If the text document contains lines with different structures, define and configure each line structure as a recordset structure.

Example for a Source File with Different Structures

Code Snippet
12345678910111213141516171819
1London20.04.2011
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
 . . .
2KK    20009999999999,9909876543219999DepositMoney
300000000001234565432,2200000000001234565432,33

The required configuration settings of this example contains three structures, which are defined with their occurrences and the names of the key field.

Content Conversion Parameters

This table lists the parameters for content conversion:

Content Conversion Parameters

ParameterValue
Document NameMT_input
Document NamespaceUrn:educationsap.com/bit/demo
Recordset NameInput
Recordset StructurePrefix,1, main,*, check,1
Recordsets per Message1
Key Field NameKey
Key Field TypeInteger

Field Names and Their Properties

You must also specify the field names, field lengths, and so on.

The following table shows the specified field names and their properties for the content conversion parameters:

Specified Field Names and Values

NameValue
prefix.keyFieldValue1
prefix.fieldFixedLengths1, 6, 10
prefix.fieldNameskey, agency, date
prefix.keyFieldInStructureIgnore
prefix.endSeparatornl
main.keyFieldValue2
main.fieldFixedLengths1, 6, 4, 13, 10, 4, 20
main.fieldNameskey, product, contract, total, GPnum, GPnumAdv, description
main.keyFieldInStructureIgnore
main.endSeparatornl
check.keyFieldValue3
check.fieldFixedLengths1, 23, 23
check.fieldNameskey, checkSum1, checkSum2
check.keyFieldInStructureIgnore
check.endSeparatornl

The result of the conversion made by the sender file/FTP adapter displays as the payload in the SAP PI message monitor of the Adapter Engine.

XML Structure after Conversion

The following code illustrates the XML structure after conversion:

The following code illustrates the XML structure after conversion:

Code Snippet
12345678910111213141516171819202122232425262728293031
<?xml version="1.0" encoding="utf-8"  ?> 
<ns:MT_Input xmlns:ns="urn:educationsap.com/bit/demo"> 
<Input> 
    <prefix> 
	<agency>London</agency> 
	<date>20.04.2011</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> 
</ns:MT_Input>

Parameters for File Content Conversion in the Sender Adapter

The parameters for file content conversion in the sender adapter are as follows:

  • Document Name

    This is the message type name and also the name of the XML document, and it is inserted in the message as the main XML tag (root).

  • Document Namespace

    This is the namespace of the message type.

  • Recordset Name

    This is the name of the structure included in the XML schema.

  • Recordset Namespace

    This namespace is appended to the name of the structure.

  • Recordset Structure

    The sequence and the number of substructures are entered as NameA, nA, NameB, nB, .... nA = 1, 2, 3, ... or * (for a variable, unlimited number including 0).

  • Recordsets per Message

    The number of recordsets to be grouped together in a message is specified. If the number of recordsets in a document is greater than the number specified, the adapter creates multiple messages from a document. The last message might then contain fewer recordsets than specified.

    Hint

    If you specify EO as the QoS, each of these messages (that is to say, each part of a document from which a message is created) is sent to the Integration Server exactly once. This action is also true for the condition in which the application is interrupted while creating the messages and restarted again later.

  • Key Field Name

    If you specify a variable number of substructures under Recordset Structure (at least one structure with the value *), then the substructures are identified by the parser from their content. This means that a key field must be set with different constants for different substructures. Specify a key field and the field name must appear in all substructures.

  • Key Field Type

    The key field type is used to compare the predefined values. Set the parameters for all the specified recordset structures NameA, NameB, and so on in the following key field types: 

    • NameA.fieldFixedLengths

      If you make an entry, the system expects a character string that contains the lengths of the structure columns as arguments separated by commas. If you also specify a separator for the columns, do not add its length to the length of the columns.

      Hint

      This entry is mandatory if you do not define NameA.fieldSeparator.

    • NameA.fieldSeparator

      If you make an entry, the system expects that the structure contains the specified character string (one or more characters) as a separator between the individual columns. If you made an entry for field FixedLengths, the extra length of the separator is taken into account, but no further consistency checks are performed. For more information about file adapters for additional parameters, see http://help.sap.com.

Configure the Sender File Adapter

Business Scenario

You want to read a text file using the Sender File Adapter.

Exercise Information

Note

In this exercise, when the values include ##, replace the character with a two-digit number (01–30).

Exercise Options

You can perform this exercise in two ways:

  1. Live Environment: choose Start Exercise, and from the entry page choose Open PDF Document. Follow the steps described in this pdf in your own system landscape.
  2. Simulation: choose Start Exercise, and from the entry page choose Start Tutorial. Watch the step-by-step instructions within the simulation.

Note

We recommend running the simulation first.
ExerciseStart Exercise

Task 1: Configure the Sender File Adapter

Steps

  1. Create a communication channel File_Sender_## for your business system BS_BIT500_##_A.

    1. Open New → Channel.

    2. Enter the following values:

      Field Name

      Value

      Channel Name

      		File_Sender_##

      Communication Component

      		BS_BIT500_##_A

    3. On the General tab page, maintain the communication channel using the following values:

      Field Name

      Value

      Direction

      		Sender

      Adapter Type

      		File (SAP BASIS 7.50)

      Transport Protocol

      		File System (NFS)

    4. On the Adapter-specific tab page, maintain the following values:

      Field Name

      Value

      Source Directory

      		/usr/sap/trans/tmp/group##

      File Name

      		xi_input.txt

    5. On the Processing tab page, maintain the following values:

      Field NameValue
      Quality of ServiceExactly Once
      Poll Interval (secs)60
      Processing ModeArchive
      Add Time StampSet the flag
      Archive Directory/usr/sap/trans/tmp/group##/archive

      For all other fields, keep the default values.

    6. Save and activate your communication channel.

  2. Change your iFlow called iFlow_MaterialA_MaterialsB_## so that the File_Sender_## is used as a sender communication channel instead of the SOAP or HTTP communication channel.

    1. Open your iFlow called iFlow_MaterialA_MaterialsB_## by double-clicking it.

    2. Select the arrow from BS_BIT500_##_A to the iFlow until the color changes to orange.

    3. Right-click and choose Assigned Referenced Channel.

    4. Select the File_Sender_## and choose OK.

    5. Choose Save. Activate and Deploy your iFlow.

  3. Set up a test for the sender file adapter.

    1. In the browser call, http://nwktdc00.wdf.sap.corp:50000/dir.

    2. Find the Additional Information → Training Information → HTTP Client Material.

    3. In the Payload XML change the namespace to use yours by replacing ## for your group number.

    4. Copy the content of the Type in XML field by selecting it and either choosing the keys <ctrl> and <c> simultaneously or doing a right-mouse-click, choose Copy.

    5. On your PI tools page http://nwktdc00.wdf.sap.corp:50000/dir, click the How to open share for file adapter files.

    6. Follow the instructions to connect to the Y: drive.

    7. In the File Download-Security Warning dialog box, choose the Open button.

    8. In the Internet Explorer-Security Warning dialog box, choose the Run button. This opens the tmp directory.

    9. In the tmp directory, choose group## folder.

    10. In the context menu of right panel of the window, choose New → Text Document. Rename the text document as xi_input.txt.

    11. Choose the text document xi_input.txt.

    12. Double-click to open the file and press the keys <ctrl><v> simultaneously or right mouse click and choose Paste.

    13. In the xi_input.txt window, choose File → Save.

    14. Exit the text document.

    15. Choose File → Close.

  4. Check the Message Monitor in the Configuration and Monitoring Home.

    1. Navigate to http://nwktdc00.wdf.sap.corp:50000/dir and choose Configuration and Monitoring Home. Alternatively http://nwktdc00.wdf.sap.corp:50000/pimon.

    2. Go to Monitoring → Adapter Engine → Message Monitor → PI Messages and check the Message List.

    3. Your Message should be Delivered, select it and check the Message Log tab to understand how the message got process.

  5. Display the file created in your directory.

    1. On your PI tools page http://nwktdc00.wdf.sap.corp:50000/dir , click How to open share for file adapter files.

    2. Follow the instructions to connect to the Y: drive.

    3. In the File Download-Security Warning dialog box, choose the Open button.

    4. In the Internet Explorer-Security Warning dialog box, choose the Run button. This opens the tmp directory.

    5. In the tmp directory, choose the folder for your group.

    6. In your group folder, you should have a folder called Archive and the file you sent should be there.

    7. In the group-folder, open the txt file and check the result, your file should not be xml anymore.

Log in to track your progress & complete quizzes

Learning

SAP FacebookSAP YoutubeSAP LinkedIn