Configuring the Receiver File/FTP Adapter 

Use

You need to 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, on the Module tab page in the module processor, you can 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 SAP Java Cryptographic Toolkit is deployed. See also: Deploying the SAP Java Cryptographic Toolkit

·        The CA certificate used to sign the server certificate must be added to the TrustedCAs keystore view. See also: 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, choose 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.

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%

·        Specify the File Name Schema that the system is to use to save the first incoming document.

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

See also Variable Substitution below.

FTP Connection Parameters

If you have selected the transport protocol File Transfer Protocol (FTP), enter the following:

·        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).

·        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 over SSL/TLS) for Control Connection

After the connection is established, the FTP control connection is protected using TLS/SSL (Transport Layer Security (BC-SEC) /Secure Sockets Layer (BC-SEC)). Data transfer is unencrypted.

¡        FTPS (FTP over SSL/TLS) for Control and Data Connection

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

If you selected FTPS for Connection Security, then 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 those expected of 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.

¡        Enter the Key Store and the X.509 Certificate and Private Key. To do this, you can use the input help.

·        To logon with the user name anonymous and the password anonymous, set the Anonymous Login indicator. Otherwise, enter the following:

¡        User Name

Enter a valid user name for the FTP server.

¡        Password with confirmation

·        Connect Mode

¡        Permanently

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 Textor 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 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. Set the Overwrite Existing File indicator 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 attached.
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.

·        Specify the document data type.

¡        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 then converted to the corresponding code page before the message is saved as a file.

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.

Variable Substitution (Target Directory/File Name Schema)

If you set the Activate indicator, you can enter variables for the Target Directory and File Name Schema. Enter the variable names and references in the table.

·        Enter each variable that you reference in the Target Directory and File Name Schema fields without the surrounding 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 schema, 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, set the Disable Security Checks indicator.

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 “..“.

Executing Operating System Commands

·        Operating System Command

An operating system command specified here is executed after a file has been successfully processed. 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 executing program continues to run in the background.

·        Terminate Program After Timeout

Set this indicator when the adapter is to terminate the executing program when the timeout is exceeded.

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

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. For more information, see Converting File Content in the Receiver Adapter.

Adapter Status

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

Advanced Mode

To specify additional parameters in the adapter configuration, set the Advanced Mode indicator.

Specify the parameter names and parameter values in the table.

Additional parameters are published in SAP Note 801926.