File Adapter Parameters

Sender File Adapter Parameters Transport Protocol The file can be selected from either a file system (File System (NFS)) or from a File Transfer Protocol (FTP) server. Message Protocol ●

To send the file content to the Integration Engine or the PCK unaltered, choose File.

●

If you want to send the Integration Engine or the PCK a text file with complex data structures that are to be converted into an XML document, choose File Content Conversion and make the required entries for conversion under Content Conversion Parameters

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. Source Tab Page File Access Parameters ●

Source Directory Specify the directory where the files to be processed are located. You can either specify the entire path name or a name relative to the working directory of the Adapter Engine. In all platforms (including Windows), use a forward slash (/) to separate directory names in accordance with Java specification.

●

File Name Specify the name of the file that you want to process.

●

Advanced Selection for Source File If you want to set an exclusion mask for the File Name specified above, or if you want to specify multiple directories using a file name mask and exclusion mask, set the Advanced Selection for Source Fileindicator. 

○

Specify an Exclusion Mask for the file name specified above.

You want to process all files that have the extension '.txt', but want to exclude all files that begin with the letter 'a'. To do this, enter *.txt for File Name, and a* for Exclusion Mask.  ○ You can enter additional specifications for source directories, file names, and exclusion masks in the table. This data is processed in addition to the details specified above.

FTP Connection Parameters Use of the file transfer protocol follows the specification RFC 959. If you have selected the transport protocol File Transfer Protocol (FTP), specify 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). ● 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). File transfer is 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 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 FTP 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 cryptography to authenticate itself. The corresponding key/certificate pair must previously be saved in a keystone view of the J2EE server by using the Visual Administrator.  ○ Enter the Keystore and the X.509 Certificate and Private Key. To do this, you can use the input help. ●

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 Permanently An existing connection to the FTP server is used permanently. The connection is reestablished automatically if it is closed by the server. 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. Processing Tab Page Processing Parameters Quality of Service Specifies how the Integration Engine/PCK should process a message. For Exactly Once in Order specify the Queue Name. More information: Quality of Service ● Poll Interval (secs) Number of seconds that the adapter must wait if no files are found for processing. ● Poll Interval (msecs) Additional waiting time in milliseconds. If you set Poll Interval (secs) to null, processing times will be short and close to real time. If you set Poll Interval (secs) and Poll Interval (msecs) to null, the adapter is only called once. ● Retry Interval (secs) Specify the number of seconds that the adapter is to wait before a file processed with errors is processed again. ●

If the value is set to null, then the adapter is canceled if an error occurs, even if a value greater than null is specified for Poll Interval (secs). If you do not enter a value, the value from Poll Interval (secs) is used. ● Processing Mode  ○ Archive Files that have been successfully processed are moved to an archive directory.  ■ To add a time stamp to a file name, select the Add Time Stamp indicator.

 



○

The time stamp has the format yyyMMdd-hhMMss-SSS. The time stamp ensures that the archived files are not overwritten and it enables you to sort them according to the time that they were received. ■ Under Archive Directory, enter the name of the archive directory. ■ If you want to archive the files on the FTP server, set the Archive Files on FTP Server indicator. If you do not set the indicator, the files are archived in the Adapter Engine file system. Delete

Successfully processed files are deleted.  ○ Test Files are not processed. Only use this mode to test the configurations of the file/FTP adapter or the Integration Engine/PCK. It is not suitable for productive operation.  ○ Set to Read-Only Successfully processed files are given this attribute. Only writable files are processed. This selection is only available for the File System (NFS) transport protocol. ● Handling of Empty Files Specify how empty files (length 0 bytes) are to be handled.  ○ Do Not Create Message No XI messages are created from empty files. The files are processed according to the selected Processing Mode. For example, if the processing mode is Delete, empty files are deleted in the source directory.  ○ Process Empty Files XI messages are created with an empty main payload. The files are processed according to the selected Processing Mode.  ○ Skip Empty Files

No XI messages are created from empty files. Empty files are skipped and remain in the source directory. ● Archive Source Files with Errors To archive source files where a permanent error occurred during processing, set the indicator. A permanent error occurs either during the conversion of the file content, or in a module in the module processor.  ○ Specify the Directory for Error Archiving.  ○ To add a time stamp to the archived file, select Add Time Stamp. Process Read-Only Files (for transport protocol File System (NFS)) Set the indicator if you want to also transfer files that are locked by other applications. Only set this indicator if you are sure that no data will be lost. ● Processing Sequence (for transport protocol File System (NFS)) If you used placeholders when specifying the file name, define the processing sequence of the files:  ○ By Name: Files are processed alphabetically by file name.  ○ By Date: Files are processed according to their time stamp in the file system, starting with the oldest file. ●

●

File Type 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 file content is converted to the UTF-8 code page before it is sent. Permitted values for the code page are the existing Char sets of the Java runtime. According to the SUN specification for the Java runtime, at least the following standard character sets must be supported:  ■ 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

XML text documents generally contain their own code page description and should be treated as Binary data type. ● Additional File(s) (for transport protocol File System (NFS)) If you want to transfer additional files, select Additional File(s). Run Operating System Command Before/After Message Processing ●

Command Line An operating system command specified here is executed before or after the message processing of a file that was found in a run. 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 (sec) 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 if 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. ●

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 convert a text file that contains complex structures into an XML source format in this mode. The file contains various row formats in logical structures. Advanced Tab Page Adapter-Specific Message Attributes To save adapter attributes in the message header of the XI message, select Set Adapter-Specific Message Attributes. To apply the following attributes in the XI message header, set the corresponding indicators:

Name

Technical Name

File Name

FileName

Directory

Directory

File Type

FileType

Character Set FileEncoding You can only set this indicator if the File Type is text, and if the File Type indicator above is already set. Source File Size

SourceFileSize

Source File Timestamp

SourceFileTimeStamp

Source FTP Host SourceFTPHost You can only set this indicator if the transport protocol is set to File Transfer Protocol (FTP). 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 in the adapter configuration, set the Advanced Modeindicator. ●

Msecs to Wait Before Modification Check Enter the number of milliseconds that the adapter must wait before it checks whether the files have been changed. This parameter is not available if you have selected File Content Conversion as the Message Protocoland then made an entry under Recordsets per Message that splits an input file into several messages.

This parameter is applicable only for the File adapter. If you enter a value in this field when configuring the sender FTP adapter, it will have no effect. ● Maximum File Size Specify the maximum file size in bytes. The adapter only processes files that are smaller than the specified size. An error occurs if files are any larger. ● Table Specify the additional parameter names and parameter values in the table.

Configuring the Receiver File Adapter Use You create a receiver file adapter to save XML messages from the Integration Server/PCK in files. Procedure 1. If you want the document that is sent from the Integration Server/PCK to be saved directly in a file, select File as the Message Protocol. 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). 2. Select Adapter Engine on the Integration Server, or select a noncentrally installed Adapter Engine. This selection is not available in the PCK. Define File Access Parameters 3. 4.

Select the Target tab page. Specify the Target Directory in which the documents are to be saved. You can enter variables for the target directory. More information: Defining Variable Substitution for Target Directory/File Name 5. 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. 6. Specify the File Name Scheme that the system is to use to save the first incoming document. You can enter variables for the file name scheme. More information: Defining Variable Substitution for Target Directory/File Name Define Processing Parameters 7. 8.

Select the Processing tab page. Select the File Construction Mode.  ○ Create The file is created. The document received last is saved in each case. If you want the created file to be overwritten, set the Overwrite Existing File indicator. If you do not set the indicator, processing is stopped until the created file is processed.  ○ Append The file is written when the inbound documents are appended.  ○ Add Time Stamp

A new file is created for each document. A time stamp with the format yyyyMMdd-HHmmss-SSS is added to the file name. 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 message ID generated by the Integration Server/PCK is added to the file name. 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. A counter, which is inserted before the file name extension, is added to the file name (for example, default002.file). Specify the following 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. If you select After First File, the counter is added when the file name is first used unchanged. If you select Immediately, the counter is added with the first inbound document.

This option is available only if you select the Transport Protocol as File System (NFS). 9. Under Write Mode, specify whether the target file is to be written Directly to 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, a time stamp is also added to the name during processing.

The scheme xitemp.tmp, for example, results in the file name xitemp.tmp. This write mode is not available for the File Construction Mode Append. 10. Select Empty Message Handling:  ○ Write Empty File An empty file (length 0 bytes) is put in the target directory.  ○ Ignore No file is put in the target directory. 11. Enter the number of messages that the adapter can process simultaneously on a cluster node under Maximum Concurrency. 12. Specify the File Type of the document.  ○ Binary  ○ Text Define Operating System Commands 13.

Specify the operating system commands that are to be executed before or after message processing. More information: Defining Operating System Commands Before/After Processing

Define Content Conversion Parameters 14.

If you have selected File Content Conversion as the Message Protocol, you can convert an XML document to a text file. Select the Content Conversion tab page. More information: Converting XML in the Receiver File/FTP Adapter to Text Format

Define Variable Substitution for Target Directory/File Name Scheme 15.

Select the Advanced tab page. More information: Defining Directory/File Name

Variable

Substitution

for

Target

Define Adapter-Specific Message Attributes A configured variable substitution (see above) is performed after the attributes from the message header are applied. 16. To evaluate adapter attributes in the message header of the PI message, set the Use Adapter-Specific Message Attributes indicator. 17. If you want missing message attributes to trigger error messages, 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 PI message header, set the corresponding indicators:  ○ File Name (technical name: FileName)  ○ Directory (technical name: Directory)  ○ File Type (technical name: FileType)  ○ File Encoding (technical name: FileEncoding) You can only set this indicator if File Type is set to Text, and if the file type indicator above is already set.  ○ Temporary Name Scheme for Target File Name (technical name: TargetTempFileName) You can only set this indicator if the target file is written using a temporary file. The attribute namespace for the adapter is http://sap.com/xi/XI/System/File. Define the Adapter Status 18.

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

Define Additional Parameters in Advanced Mode 19. 20.

To specify additional parameters in the adapter configuration, set the Advanced Mode indicator. Specify the additional parameter names and parameter values in the table