Entering content frame

Procedure documentation Configuring the Receiver File/FTP Adapter Locate the document in its SAP Library structure

Use

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

To configure the adapter you must specify the following:

·        A directory and rule to determine the file names under which inbound messages are saved.

·        A dispatcher class (optional) with the corresponding settings and the user exits and their settings that are to be called by the dispatcher.

·        The address (HTTP port and URL) where the adapter can be contacted from the Integration Engine.

·        Rules to convert an XML text file that represents a simple table structure, to a text document with columns of fixed length or columns that are separated by particular characters, or both (these specifications are optional).

Prerequisites

You have:

...

       1.      Installed the corresponding adapter.

       2.      Selected the adapter on the configuration screen.

       3.      Called the adapter configuration by choosing Configure.

Procedure

The configuration of the receiver file/FTP adapter comprises five functional subareas:

...

       1.      The Java class name for the receiver file/FTP adapter

Specify the class name as follows:

classname=com.sap.aii.messaging.adapter.ModuleXMB2FILE

This specification is mandatory.

       2.      The version specification for the configuration

version=30

This specification is mandatory. If no specification is entered, the configuration is interpreted as an XI 2.0 adapter configuration. Other values are not permitted and trigger an error.

       3.      File/FTP adapter mode

Specify the mode of the receiver file/FTP adapter. The following values are permitted:

¡        mode=XMB2FILE

The system saves the document sent from the Integration Engine as a file.

¡        mode=XMB2FILEWITHCONVERSION

A text file is expected that contains an XML document that represents a table. This document can be converted to a text file that stores the contents of the document as a list, with elements separated by commas or with fixed column lengths. The expected XML format corresponds to the result of the conversion of the sender JDBC or file/FTP adapter. You must make the necessary specifications for the conversion in step 5.

¡        mode=XMBSTREAM2FILE

A special file format is generated here that represents a completely serialized Integration Engine message. This file format can be processed by the sender file/FTP adapter in the mode FILE2XMBSTREAM. This format can be used to temporarily save complete Integration Engine messages, including all Integration Engine-specific parameters that then no longer need to be specified in the sender file/FTP adapter.

The default value is XMB2FILE.

       4.      The dispatcher class and the user exits to be called by the dispatcher (optional)

The receiver file/FTP adapter provides you with a dispatcher that you can use to convert messages after they have been received. The settings required for the dispatcher are explained in the example.

       5.      Specifications for addressing by the Integration Engine

¡        XI.httpPort=<port_no>

<port_no> specifies the HTTP server port that receives the messages from the Integration Engine.

¡        XI.httpService=<service>

<service> describes the service part of the address where the Integration Engine must send its messages.

These specifications are mandatory.

Note

If, for example, you have specified XI.httpPort=1234 and XI.httpService=/file/Receiver, the end point address of the file/FTP adapter in the Integration Engine must be specified as follows:

http://<fileadapterhost>:1234/file/Receiver

Caution

The end point address must be extended as follows for the Integration Engine in Release 1.0:

http://<fileadapterhost>:1234/file/Receiver?action=execute&pipelineid=Receiver

If the Integration Engine message is sent to a non-specified adapter service, the system displays the following error message:

No registered listener for <Service> found

The system displays the same message if the adapter is initialized, but has not been started (status STOPPED or INITIALIZED).

¡        XI.ReceiverAdapterForService=<Service>

This specification is optional.

<Service> is the logical name of a business system in the System Landscape Directory (SLD). If the Adapter Engine connection to the SLD is configured, an association for the receiver file/FTP adapter is created for this business system. When you create an end point for this business system in the Integration Directory, the address of the adapter is determined from this association as the default value.

If no connection can be established with the SLD, or if the business system does not exist in the SLD, the specification is meaningless.

       6.      Specifications for file processing:

¡        file.createDir=<n>

Specify whether a target directory (targetDir) should be created (1) or not (0), if one does not already exist.  The default value is 1 (create directory).

The following specifications are mandatory:

¡        file.targetDir=<directoryName>

Specify the target directory where incoming documents are to be saved. The system creates this directory automatically if you do not make any specifications for file.createDir.

¡        file.targetFilename=<fileName>

Specify the file name where the system is to save the first incoming document.

¡        file.writeMode=<mode>

Specify whether the system is to save all inbound documents under the file name that you specified in file.targetFilename. The following values are permitted:

§         file.writeMode=overwrite

In mode overwrite, the file is overwritten so that the system always only saves the last received document.

§         file.writeMode=append

In append mode the file is updated by appending the incoming documents.

§         file.writeMode=addTimeStamp

In mode addTimestampthe system generates a new file for each document. The file name comprises the name specified under file.targetFilename, in each case extended by a time stamp in the format yyyyMMdd-HHmmss-SSS. This corresponds to the time that the document was processed, from the year (yyyy) to the millisecond (–SSS), which is inserted before the file name extension.

This mode guarantees that no data is overwritten. In this way, files that originate from the same adapter configuration can simply be sorted according to the date that they entered processing.

§         file.writeMode=addMessageId

In mode addMessageIdthe system generates a new file for each document. The file name comprises the name specified under file.targetFilename and the message ID (GUID) used by the Integration Server in the format xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

This mode guarantees that no data is overwritten.

§         file.writeMode=addCounter

In mode addCounterthe system generates a new file for each document. The file name comprises the name specified in file.targetFilename, extended by one counter that is added before the file name extension (for example, default002.file). The counter is constructed from the subsequent specifications.

The mode addCounterguarantees that no data is overwritten. If necessary, the system finds the next free counter from which it can construct a new file name.

In mode addCounterthe exact format of the file name can be controlled using the following parameters; each parameter has a default setting.

¡        file.counterSeparator=<SeparatorString>

Specify one or more characters that you want to add before the counter in the file name. The default value is an empty character sequence (that is, no SeparatorString).

¡        file.counterFormat=<FormatString>

Specify the first counter to be used. It must be a valid integer number, though leading zeros are permitted. The length of the FormatString is used for all counters (including existing leading zeros) until overflow forces the format to be enlarged.

The default value is 000.

¡        file.counterStep=<StepNo>

Enter a number that specifies the increment of the counter that successive counters are to be increased by. The default value is 1.

¡        file.counterMode=<counterMode>

Specify when a counter is to be added. The following values are permitted:

§         file.counterMode=afterFirst

The counter is not added until the file name specified under file.targetFilename is used unaltered.

§         file.counterMode=immediately

The counter is added after the first incoming document.

The default value is afterFirst.

Example

If you do not set a parameter, the system generates the file names <default.file>,<default000.file>, <default001.file>, <default002.file> from the specified default values for incoming documents.

If instead of the default values, you set the following explicit values

file.targetFilename=test.dat

file.counterMode=immediately

file.counterSeparator=_

file.counterFormat=00005

file.counterStep=2

the system generates the file names test_00005.dat, test_00007.dat, test_00009.dat, and so on.

This list is also continued once the adapter has been stopped and restarted, without overwriting existing files.

¡        file.encoding=<codepage>

This parameter is optional.

The default value for binary data is the code page used by the Integration Server (that is, the data is saved without being changed). The default value for text data is the system code page of the Adapter Engine (that is, the text data coded by the Integration Server in UTF-8 is converted accordingly).

If file.encoding is specified and the Integration Server sends binary data, this is interpreted as text coded in UTF-8.

¡        file.execute=<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).

You can also enter the currently processed file name with the placeholder %f (file name) or %F (absolute filename including path) in the operating system command.

¡        file.exactlyOnceHandlingIDsExpiration=<n Days>

Specify the number of days that the management information for received messages with the service attribute Exactly Once (In Order) should be kept. This information is required to avoid messages being duplicated, if when handling an error the Integration Engine sends the same message to an adapter more than once. The default value is 60 days.

Caution

If the value is set to 0 or to a negative value, all management information is deleted each time the adapter is initialized. This can be useful for test purposes but must not be used for production operation.

If a message is received with the service attribute Exactly Once, a temporary file with the name of the adapter configuration is generated first in the target directory. This file is then automatically renamed during the Exactly Once handling. It must not be renamed or edited manually in any way, or deleted since this can lead to the message being lost.

If you want to save files on an FTP server and not in the file system, you need to make the following additional specifications:

This graphic is explained in the accompanying text

In the FTP client mode, the value addCounter is not permitted for the parameter file.writeMode.

¡        ftp.host=<ftp-server>

The host name or IP address of the FTP server. If this specification is available, it is assumed that you are accessing an FTP server. The specifications file.targetDir and file.targetFileName refer to the FTP server.

¡        ftp.port=<port-no.>

The port number of the FTP server. It is not obligatory that you specify the port number here. The default is the standard port for the FTP server (21).

¡        ftp.user=<user name>

¡        ftp.password=<password>

A valid user name for the FTP server. It is not obligatory that you specify a user name. The default user is anonymous with the password anonymous.

¡        ftp.connection=perFileTransfer|permanently

Use this specification to define whether a new connection needs to be established each time a file is transferred to the FTP server (value perFileTransfer), or whether a permanent connection should be used (value permanently). In this case, the connection is re-established automatically if it closed on the server side (for example, due to a timeout). The default value is permanently.

¡        ftp.putSafe=YES|NO

Use this specification to define whether a transferred file is first created with a temporary name and only renamed once the transfer is complete (YES), or whether it is created with its final name at the start of the transfer (NO). The latter case can lead to problems if an application on the FTP server accesses the file before the transfer is complete. If you specify YES, this problem is avoided because the file only becomes visible with the search name when the transfer is complete.

The default value is NO.

       7.      Specifications to convert an XML document (mode XMB2FILEWITHCONVERSION)

The following arguments refer to the mode XMB2FILEWITHCONVERSION. In another mode the arguments subsequently executed are ignored.

To convert a table in XML format to pure text format, the document format must be the same as that which is generated by the sender file/FTP adapter in mode FILE2XMBWITHROWCONVERSION (with the default value <row> for the structure) and the sender JDBC adapter. This means that the document structure looks like this:

<resultset>

<row>

<column-name1>column-value</column-name1>

<column-name2>column-value</column-name2>

<column-name3>column-value</column-name3>

</row>

<row>

<column-name1>column-value</column-name1>

<column-name2>column-value</column-name2>

<column-name3>column-value</column-name3>

</row>

</resultset>

This is an example for 3 columns and 2 lines. The number of lines and columns is, of course, unlimited. The XML elements in italics can be defined by the user and the elements of a line must be grouped within an element of type <row> … </row>. Using the following specifications, the system constructs a text file from this XML document.

¡        xml.addHeaderLine=<n>

Specify whether the text file should have a header line with column names. The following values are permitted:

§         0 – No header line

§         1 – Header line with column names from the XML document

§         2 – as for 1, followed by a blank line

§         3 – Header line is stored as xml.headerLine in the configuration and is applied

§         4 – as for 3, followed by a blank line

This specification is mandatory.

¡        xml.headerLine=<headerLineString>

Specify the header line that is generated in the text file if xml.addHeaderLine has the value 3 or 4. This specification is mandatory.

¡        xml.fieldFixedLengths=<String>

Specify a character string that contains a list of fixed column widths that are separated by commas and which determine the number and the length of columns generated in the text file.

If you do not make any specifications for xml.fieldSeparator, the specification xml.fieldFixedLengths is mandatory.

¡        xml.fixedLengthTooShortHandling=<handling>

Specify how you want the system to respond when column widths in the actual document exceed those defined in xml.fieldFixedLengths. The following values are permitted:

§         xml.fixedLengthTooShortHandling=Error

Error means that processing of the document is terminated.

§         xml.fixedLengthTooShortHandling=Cut

Cut means that a value is shortened to the maximum permitted length.

§         xml.fixedLengthTooShortHandling=Ignore

Ignore means that the system applies the value completely, regardless of it being too long. Subsequent columns are moved correspondingly.

The default value is Error.

If you do not specify xml.fieldFixedLengths, this specification is obsolete.

¡        xml.fieldSeparator=<SeparatorString>

If you specify a character string here, it is added as a separator to all columns except the last. You can also specify this string in addition to xml.fieldFixedLengths.

If you made no specification for xml.fieldFixedLengths, this is the only specification to identify the individual columns in a row.

If you made a specification for xml.fieldFixedLengths, the length of the separator is not taken into account.

This graphic is explained in the accompanying text

You must specify at least either xml.fieldFixedLengths orxml.fieldSeparator.

If you have only specified xml.fieldSeparator, the structures of the XML document can have differing numbers of elements that are added to each other separately in the text file by the value from xml.fieldSeparator. If you specify xml.fieldFixedLengths this is not possible since the number of columns is defined when the column widths are given.

¡        xml.endSeparator=<lastSeparatorString>

If you enter a character string here, the system adds it to the last column as a closing character. You can also make this specification in addition to xml.fieldFixedLengths. To include a line break following the closing character, you must explicitly define it by attaching ´nl´ (including the quotation marks) to the string.

The default value is a line break (no explicit separator after the last column; instead the structures are arranged line-by-line).

¡        xml.beginSeparator=<firstSeparatorString>

If you specify a character string here, the system places it before the first column. You can also make this specification in addition to xml.fieldFixedLengths.

The default value is an empty character string (no separator before the first column).

This graphic is explained in the accompanying text

Special Characters in the String for Separators:

In all strings for separators (xml.fieldSeparator, xml.beginSeparator and xml.endSeparator), you can specify non-printable ASCII characters. These characters can each be inserted individually in the string in the form ´0xHH´ (including the quotation mark), where HH represents the character coded as a hexadecimal value. A line break can be entered using the character ´nl´ (including the quotation marks); nl stands for new line. The special character ´0´ is not a separator character.

This graphic is explained in the accompanying text

Fixed Column Width of the Text Document:

xml.absoluteRowWidth=<noOfColumns>

If the separators do not contain any line breaks, the text document is generated as a single line text. To restrict the width of the text, use this parameter. <noOfColumns> represents the maximum number of columns in this case. This parameter also functions together with the specification of a line break for xml.endSeparator.

This value requires xml.addHeaderLine=0 to be specified.

 

 

Leaving content frame