Show TOC

Configuring the Receiver File/FTP AdapterLocate this document in the navigation 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=1234XI.httpService=/file/Receiver
    and , 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

    Die gleiche Fehlermeldung erhält man, wenn der Adapter initialisiert, aber nicht gestartet ist (sich also im Status ANGEHALTEN oder INITIALISIERTbefindet).

    • XI.ReceiverAdapterForService=
      <Service>

      This entry 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 (
      101
      ) or not (), if one does not already exist. The default value is (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
        (veraltet)
        In mode
        overwrite
        , the file is overwritten so that the system always only saves the last received document.

        This parameter is replaced by file.overWrite.

      • file.writeMode=
        append
        In
        append
        mode the file is updated by appending the incoming documents.
      • file.writeMode=
        addTimeStamp
        In mode
        addTimestamp
        the 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
        addMessageId
        the 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
        addCounterdefault002.file
        the 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, ). The counter is constructed from the subsequent specifications.
        The mode
        addCounter
        guarantees 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
        addCounter
        the 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

        Only add the counter after the file name specified under file.targetFilename was used unaltered.

      • file.counterMode=
        immediately

        The counter is added after the first incoming document.

      The default value is
      afterFirst
      .

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

then the file names test_00005.dat, test_00007.dat, and test_00009.dat etc. will be created.

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

  • file.overWrite=true|false

    Define if a file with a file name that already exists in the target directory is to be overwritten. The default value is false which means an existing file in the target directory is overwritten. If you set the value to true, this existing file is not overwritten.

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

    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.

  • 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:

Note
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 made, 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
    anonymousanonymous
    with the password .
  • 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). Vorschlagswert ist
    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.

  1. 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 will 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
    • 21
      - as for , followed by a blank line
    • 3
      - Header line is stored as xml.headerLine in the configuration and is applied
    • 43
      - as for , 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
    34
    or . This specification is mandatory.
  • xml.fieldFixedLengths=
    <String>

    Specify a character string containing a list of fixed column widths that are separated by commas and 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 copies the value completely, regardless of it being too long. Subsequent columns are moved accordingly.
    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.

    Note

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

    Note

    Special Characters in the Strings 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´HH´nl´
    (including the quotation mark), where represents the character encoded as a hexadecimal value. A line break can be entered using the character (including the quotation marks); nl stands for new line. The special character ´0´ is not a separator character.
    Note

    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.

  1. The adapter can send back a synchronous system acknowledgement if the sender requests it. The acknowledgment confirms that the message was delivered to the receiver.
    • If you want to send back a synchronous system acknowledgment, set XI.AckFinal=true. This is the default.
    • If you want to prevent a synchronous system acknowledgement from being sent back, even if the sender requests it, set XI.AckFinal=false.