Configuring the Receiver File/FTP Adapter 

Use

You configure the receiver file/FTP adapter to save XML messages from the Integration Server/PCK in files. 

Integration

You configure the adapter on the Parameters tab page during the definition of a communication channel in the Integration Server or in the PCK. In addition to the adapter configuration, you can use the Module tab page in the module processor to specify generic modules, which give the adapter additional functions.

Prerequisites

       1.      You have created a new communication channel or have opened an existing one.

       2.      On the Parameters tab page you have selected the adapter type FILE.

       3.      You have selected the Receiver radio button to define the adapter as a receiver adapter.

Using FTPS (File Transfer Protocol Using SSL/TLS)

The use of FTPS follows the specification RFC 4217.

The CA certificate used to sign the server certificate must be added to the TrustedCAs keystore view.

See: Key Storage Service

Activities

To configure the adapter, specify the following:

Transport Protocol

The file can either be put in a file system (File System (NFS)) or on a File Transfer Protocol (FTP) server.

Message Protocol

●      File

The document sent from the Integration Server/PCK is saved directly as a file.

●      If you want to convert an XML document to a text file, select File Content Conversion and make the required entries for conversion under Content Conversion Parameters (see below).

Adapter Engine

Select the Adapter Engine on the Integration Server, or select a non-centrally installed Adapter Engine. This selection is not available in the PCK.

Target Tab Page

File Access Parameters

●      Specify the Target Directory in which the documents are to be saved.

You can enter variables for the target directory. The variables must be enclosed by % characters.

c:/temp/local/%var1%

●      If you want the adapter to create the target directory if it does not exist, select Create Target Directory.

If the indicator is not set and the target directory does not exist, the adapter returns an error.

●      Specify the File Name Schemethat the system is to use to save the first incoming document.

You can enter variables for the file name scheme. The variables must be enclosed by % characters.

See also Variable Substitution below.

FTP Connection Parameters

The application of the File Transfer Protocol follows the RFC 959 specification. If you have selected the transport protocol File Transfer Protocol (FTP), enter the following information:

●      Server

Enter the host name or IP address of the FTP server.

●      Port

Specify the port number of the FTP server. The default is the standard port for the FTP server (21).

●      Data Connection

○       Active

In active mode, the server establishes a data connection from its data port, port 20, to an end point chosen by the client.

○       Passive

In passive mode, the client establishes a data connection to the port required by the server.

The default setting is a passive data connection. Only change this setting if you have a specific reason.

●      Timeout (secs.)

If no data is transferred between the client and the FTP server in the time interval specified here, the adapter interprets this as an error and terminates the transfer.

●      Connection Security

○       None

The FTP protocol is used without encryption.

○       FTPS (FTP Using SSL/TLS) for Control Connection

The FTP control connection is protected using TLS/SSL (Transport Layer Security/Secure Sockets Layer) once the connection has been established successfully. Data is transferred unencrypted.

○       FTPS (FTP Using SSL/TLS) for Control and Data Connection

All communication with the FTP server is encrypted and uses TLS/SSL.

If you have selected FTPS for Connection Security, enter the following details:

○       Command Order

Specifies the sequence of commands used to authenticate and secure the connection.

Retain the default setting. Only adjust the sequence of commands to match the sequence expected by the FTP server if you encounter problems with the TLS connection. For information about the correct setting, see the documentation for the FTP server.

○       Use X.509 Certificate for Client Authentication

Set this indicator if the adapter, in contrast to the FTP server, is to use X.509 certificate and public-key encryption to authenticate itself. The corresponding key/certificate pair must previously be saved in a keystore view of the J2EE server by using the Visual Administrator.

○       Select the Keystore and the X.509 Certificate and Private Key.

●      To log on anonymously, select Anonymous Login.

Otherwise, enter the following:

○       User name

Enter a valid user name for the FTP server.

○       Password with confirmation

●      Connect Mode

○       Permanent

An existing connection to the FTP server is used permanently.

The connection is reestablished automatically if it is lost on the server side.

○       Per File Transfer

A new connection to the FTP server is established for each file transfer.

●      Transfer Mode

Set the FTP connection transfer mode to Text or to Binary.

●      Put File

If the file is to be created on the server immediately, select Directly.

If the content is to be gathered in a temporary file first before the final file is put on the server, choose Use Temporary File.

Processing Tab Page

Processing Parameters

●      Various options exist for creating the files:

File Construction Mode

Mode	Selection
Create	The file is created. The document received last is saved in each case. Select Overwrite Existing File if you want to overwrite the existing file. If you do not set the indicator, processing is stopped until the created file is processed. You can only set the indicator if you have selected Use Temporary File under Put File.
Append	The file is written when the inbound document is appended.
Add Time Stamp	A new file is created for each document. Each file is extended with a time stamp with the format yyyyMMdd-HHmmss-SSS. The time stamp is added as the last part of the name before the extension. This mode guarantees that no file is overwritten. In this way, files that originate from the same adapter configuration can be sorted.
Add Message ID	A new file is created for each document. The file name is extended by the message ID generated by the Integration Server/PCK. The ID has the format: xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. The message ID is added as the last part of the name before the extension. This mode guarantees that no file is overwritten.
Add Counter	A new file is created for each document. The file name is extended with a counter, which is inserted before the file name extension (for example, default002.file). This selection is only available for the File System (NFS) transport protocol. Make specifications for Counter Definition: ●      Prefix Specify one or more characters that you want to add before the counter in the file name. ●      Format Specify the first counter to be used. It must be a valid integer number. Leading zeros are permitted. ●      Step Specify the counter increment. ●      Mode Specify when the counter is to be added. ○       After First File The counter is added when the file name is used unaltered for the first time. ○       Immediately The counter is added with the first document.

●      Under Write Mode, specify whether the target file is to be written directly in the specified directory. If an additional step is to be added using a temporary file, choose Use Temporary File.

●      You can specify a naming scheme for the temporary file under Temporary File Name Scheme.

This scheme is used to determine the prefix and extension of the temporary file; to ensure a unique file name, the message ID is also added to the name during processing.

The schema xitemp.tmp, for example, results in the file name xitemp<timestamp>.tmp.

●      Select Handling of Empty Messages:

○       Write Empty File

An empty file (length 0 bytes) is put in the target directory.

○       Ignore

No file is put in the target directory.

●      Under Maximum Concurrency, specify how many messages the adapter is to process in parallel in a cluster node.

●      Select the File Type of the document:

○       Binary

○       Text

Under File Encoding, specify a code page. The default setting is to use the system code page that is specific to the configuration of the installed operating system.

The content of the message is converted to the corresponding code page before the message is saved as a file.

You should use this conversion only for plain text and not for XML documents. If you want to change the encoding of an XML document, then select the File Type as Binary and apply XMLAnonymizerBean as an additional module in the Module tab page.

Permitted values for the code page are the existing Charsets of the Java runtime. According to the SUN specification for the Java runtime, at least the following standard character sets must be supported:

Java Runtime Character Sets

Character Set	Description
US-ASCII	Seven-bit ASCII, also known as ISO646-US, or Basic Latin block of the Unicode character set
ISO -8859-1	ISO character set for Western European languages (Latin Alphabet No. 1), also known as ISO-LATIN-1
UTF-8	8-bit Unicode character format
UTF-16BE	16-bit Unicode character format, big-endian byte order
UTF-16LE	16-bit Unicode character format, little-endian byte order
UTF-16	16-bit Unicode character format, byte order

Check which other character sets are supported in the documentation for your Java runtime implementation.

Run Operating System Command Before/After Message Processing

●      Command Line

The operating system command specified here is executed before or after successful file processing. The default value is an empty character string (no command).

When the operating system command is called, the file name currently being processed can be specified with the following placeholders:

●    %f (file name)

●    %F (absolute file name including path)

●      Timeout (secs.)

This specifies the maximum runtime of the executing program in seconds. When this time interval is exceeded, the adapter continues processing. The executable program continues to run in the background.

●      Terminate Program After Timeout

Set this indicator if the adapter is to terminate the executing program in the event of a timeout.

The adapter writes the output (STDOUT and STDERR) for the operating system command in the system trace.

Message processing is independent of any errors that occur during the execution of a configured operating system command.

Content Conversion Tab Page

Content Conversion Parameters

If you have selected File Content Conversion as the message protocol, you can create a text file from an XML document in this mode.

More information: Converting File Content in the Receiver Adapter

Advanced Tab Page

Variable Substitution (Target Directory/File Name Scheme)

If you set the Enable indicator, you can enter variables for the Target Directory and File Name Scheme. Enter details for the names of the variables and references in the table.

●      Enter each variable that you reference in the entry for Target Directory and File Name Scheme without the enclosing percentage sign under Variable Name in the table.

The variables can refer to attributes of the message header or elements of the message payload.

○       If the variables are to refer to an attribute of the message header, add the prefix message: to the name of the variable under Reference. You can specify the following attributes of the message header:

sender_party, sender_service, receiver_party, receiver_service, interface_name, interface_namespace

message_id (message ID with hyphens, for example 9fbe1ff1-9a0d-11d9-8665-cbf10a126331)

message_id_hex (Message ID in hexadecimal format for example 9fbe1ff19a0d11d98665cbf10a126331)

For example, if you want to specify the interface name from the message header in the target directory or in the file name scheme, enter message:interface_name as the reference.

If one of the message attributes contains characters that are not permitted in a file name, for example \, /, :, *, ?, ", <, >, |, then these characters are replaced by an underscore ("_").

If the variable refers to an element in XML schema, add the prefix payload: to the information under Reference. The reference then comprises a pseudo path description in the form of a comma-separated list with the schema namea,na,nameb,nb,....

namea,nameb,... corresponds to the element name and na,nb,... corresponds to the occurrence of the element name at the respective level in the document.

The description begins at the root of the document and ends at the respective element.

To reference the element that is in bold in the example, the following expression is used: payload:root,1,e1,1,e2,2

The parser searches for the first occurrence of the root element at the first level. It then searches for the first occurrence of e1 at the second level and for the second occurrence of e2 at the third level. The content of the last element (“Example Value”) is set as the value for a specified variable.

 

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

<root>

  <dummy>

     <e1>

        <e2>Data_1</e2>

        <f/>

        <g attr="abc">text</g>

        <e2>Data_2</e2>

     </e1>

  </dummy>

  <e1>

     <e2>illegal/value</e2>

     <f/>

     <g attr="abc">text</g>

     <e2 attr="fghij">Example Value</e2>

  </e1>

</root>

●      To disable the check the adapter performs for the element data, choose Disable Security Checks.

Otherwise, the adapter checks whether the element data contains characters that could lead to security risks in the file system environment. The check includes the characters “/“, “\“, and “..“.

Adapter-Specific Message Attributes

A configured variable substitution (see above) is performed after the attributes from the message header are applied.

●      To evaluate adapter attributes in the message header of the XI message, select Use Adapter-Specific Message Attributes.

●      If you want missing message attributes to trigger an error message, select Fail If Adapter-Specific Message Attributes Missing. If the indicator is set and the header for adapter-specific message attributes or one of the set attributes is missing from the message, this leads, in asynchronous cases, to a delivery exception in the audit log of the message. In synchronous cases, the sender of the message is notified.

If you do not set the indicator, and message attributes are missing, the adapter accesses information from the adapter configuration.

To evaluate the following attributes in the XI message header, set the corresponding indicators:

Name	Technical name
File Name	FileName
Directory	Directory
File Type	FileType
File Encoding You can only set this indicator if the file type is text, and if the file type indicator above is already set.	FileEncoding
Temporary Name Scheme for Target File Name You can only set this indicator if the target file is written using a temporary file.	TargetTempFileName

The attribute namespace for the adapter is http://sap.com/xi/XI/System/File.

Adapter Status

Set the adapter to Active to enable messages to be exchanged.

Advanced Mode

To specify additional parameters for the adapter configuration, select Advanced Mode.

Specify the parameter names and parameter values in the table.

Additional parameters are published in SAP Note 801926.