Configuring the Sender File/FTP Adapter

Use

You need to configure the sender file/FTP adapter to send file contents to the Integration Engine.

To configure the adapter you must specify the following:

A directory and file name with a placeholder (*) to select the files
A processing rule for successfully sent data
Simple routines to convert a text file (with columns of fixed length or columns that are separated by particular characters, or both) to an XML document (these specifications are optional).
A dispatcher class (optional) with the corresponding settings and the user exits and their settings that are to be called by the dispatcher
Sender and receiver data required by the Integration Engine for routing and mapping

Prerequisites

You have:

Installed the corresponding adapter.
Selected the adapter on the configuration screen.
Called the adapter configuration by choosing Configure.

Procedure

The configuration of the sender file/FTP adapter comprises five functional sub areas:

The Java class name for the sender file/FTP adapter
Specify the class name as follows:
classname=
```
com.sap.aii.messaging.adapter.ModuleFile2XMB
```
This specification is mandatory.
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.
File/FTP adapter mode
Specify the mode of the sender file/FTP adapter. The following values are permitted:
- mode=
```
FILE2XMB
```
  The content of the file is sent directly to the Integration Engine.
- mode=
```
FILE2XMBWITHROWCONVERSION
```
  The system expects a text file that contains identically structured rows that can be converted into an XML document. To make this type of conversion, you must make the necessary specifications in step 7.
- mode=
```
FILE2XMBWITHSTRUCTURECONVERSION
```
  The system expects a text file with more complex file structures that can be converted into an XML document. A file of this type contains various row formats in logical structures. To make this type of conversion, you must make the necessary specifications in step 8.
- mode=
```
FILE2XMBSTREAM
```
  A special file format is expected here that represents a completely serialized Integration Engine message. This file format can be generated from the receiver file/FTP adapter in the mode XMBSTREAM2FILE. This format can therefore be used to temporarily save complete Integration Engine messages, including all Integration Engine-specific parameters as described under point 5. Therefore, in this mode only the parameters for logging on to the Integration Engine (that is, XI.TargetURL, if necessary XI.User, XI.Password, XI.Client, and XI.Language) are evaluated from the configuration.
The default value is
```
FILE2XMB
```
.
The dispatcher class and the user exits to be called by the dispatcher (optional)
The sender file/FTP adapter provides you with a dispatcher that you can use to convert messages before they are sent. The settings required for the dispatcher are explained in the example .
Specifications for the Integration Engine
Enter the complete address (URL) of the Integration Engine that you want to send the message to:
XI.TargetURL=
```
http://IntegrationEngineHost:port/pipeline-arguments
```
This specification is mandatory.

Enter a target URL for authentication with certificate that supports the HTTPS protocol.
Note
The Integration Engine address can also be accessed dynamically from the SAP System Landscape Directory (SLD). The following entry is added to the configuration for this purpose:
XI.SLDConfiguration=
```
SLDaccessor
```
In this case the URL of the corresponding Integration Server for the system specified with XI.SenderService is read from the SLD and used instead of the value specified under XI.TargetURL. Therefore, specify the following:
XI.TargetURL=
```
<fromSLD>
```
To be able to access the SLD, the SLDaccessor service must be configured correspondingly and the respective entries must be maintained in the SLD.
Note
If the Integration Server is accessed by means of an HTTP proxy server rather than directly, the following parameters must be set:

XI.proxyHost=<proxyHostname>

XI.proxyPort=<proxyPortnumber>
<proxyHostname> is the host name of the proxy and <proxyPortnumber> is the port where the proxy receives HTTP requests (for example,
```
8080
```
).
If an authentication was specified for the specified URL (HTTP service) in the Integration Engine, the following specifications are mandatory:
- XI.User=<user-name>
- XI.Password=<password>
  Note
  The specifications must match those that you made in transaction SICF in the Integration Engine. If you do not specify a user and password combination, or the combination is invalid, the system will terminate each attempt to access the Integration Engine with the message Transport Exception: http-Error 401 - Unauthorized.
  
  The user must have the authorizations of group SAP_XI_APPL_SERV_USER on the Integration Server.
If an authentication with certificate was specified for the specified URL (HTTPS service) in the Integration Engine, the following specifications are mandatory:
- Enter the path to the key pair under SSLcertificate.
  Enter the path relative to the installation directory for the Adapter Engine.
  
  The key pair must be in P12 or PFX file format.
- To protect the key pair file, you can enter a password for parameter SSLcertificatePassword.
- To check the server certificate by using the certificate in certificate management, enter SSLauthentication=true.
If you want to use a different client or language to the default setting in the Integration Engine when logging on, you can also set the following parameters:
- XI.Client=<client-no>
- XI.Language=<language-id>
You can set the following arguments (except in mode FILE2XMBSTREAM) and use them to identify the adapter configuration during routing and mapping in the Integration Engine pipeline. You can also find an explanation about each argument there.
- XI.SenderParty=<sender party name>
- XI.SenderService=<sender service name>
- XI.InterfaceNamespace=<
```
namespace URI>
```
- XI.Interface=<
```
name>
```
- XI.ReceiverParty=<receiverparty name>
- XI.ReceiverService=<receiver service name
```
>
```
  Note
  You must set at least XI.SenderServiceand XI.Interface and XI.InterfaceNamespace. The receiver is generally determined by routing in the Integration Engine. This specification is not mandatory.
- XI.QualityOfService=<
```
QualityOfService>
```
  Specifies how the Integration Engine should process a message. The following values are permitted:
  - XI.QualityOfService=
```
BE
```
    (Best Effort: synchronous processing)
  - XI.QualityOfService=
```
EO
```
    (Exactly Once: asynchronous processing with guaranteed execution exactly once)
  - XI.QualityOfService=
```
EOIO
```
    (Exactly Once in Order: asynchronous processing using queues, that is, guaranteed execution exactly once and maintaining the sequence of successive messages)
  You must also define a queue name for
```
EOIO
```
  :
- XI.QueueId=<
```
QueueName>
```
  This queue name is used in the Integration Engine to process messages in the same sequence that they arrived in.
Specifications for file selection and processing mode
The following specifications are mandatory:
- ```
file.type=
```
  BIN|TXT
  Use this parameter to specify whether the file is to be read as a text file or a binary file. With a binary file, the data is transferred unchanged, and with a text file you can define a code page by using the parameter
```
file.encoding
```
  (see below). The default setting is the code page of the host on which the Adapter Engine is running.
- file.sourceDir=<
```
directory_name>
```
  Specify the directory where the files to be processed are located.
  You can either specify the entire name or a name relative to the working directory of the Adapter Engine. On all platforms (including Windows), use a forward slash (
```
/
```
  ) to separate directory names in accordance with the Java specification.
- file.sourceFileName=<
```
filename>
```
  Specify the name of the file that you want to process.
  
  The name can contain a placeholder (*) at any point, so as to be able to select a list of files for processing.
  The following are valid examples for
```
filename
```
  :
```
myFile.txt
```
```
my*.txt
```
```
*.txt
```
```
*File.*
```
```
*File*.*
```
```
my*le.*
```
  Names that comprise more than two parts are also permitted.
- file.pollInterval=
  Specify the number of seconds that the adapter must wait if no files for processing can be found.
  
  You can also specify the following parameters so as to specify an additional waiting time in milliseconds:
  
  file.pollIntervalMsecs=
  
  If file.pollInterval is set to 0, then very short, almost real time processing times can be achieved.
  
  The default value for this parameter is 0.
  
  If the call is not to be repeated then you must set both parameters to 0 (or just the parameter file.pollInterval if you have not specified a value for parameter file.pollIntervalMsecs).
  
  In this case the adapter status remains as STARTED. To initiate a new call, choose Stop/Start or Restart to restart the adapter.
- file.retryInterval=
  Specify the number of seconds that the adapter is to wait before a file processed with errors is processed again.
  
  The value from file.pollIntervalis applied as the default value. If this value is 0 (the file is not processed again), then files processed with errors are not processed again.
  
  If file.retryInterval is also 0, then the adapter is terminated if an error occurs, even when a value greater than 0 was specified for file.pollInterval. In this case the adapter status remains as STARTED. To process the file again, choose Stop/Start or Restart to restart the adapter.
- file.checkFileModificationInterval=<msecs>
  Use this parameter to define a length of time (default value: 0) for the file/FTP adapter to wait after the file has been read to see if the file length changes. If this is the case, the system repeats the read procedure. This is useful if the files to be imported by the adapter are generated dynamically without being locked on the operating system level (for example, files received from FTP servers). Without this workaround, the file/FTP adapter cannot recognize whether the generation of the file is complete in such applications with operating system functions.
- file.logPollInterval=NO|YES
  All entries to loops that last longer than 5 seconds are shown in the adapter log by default. As a result, this can lead to a lot of entries in the log. In such instances, the log output (but not the loop itself) can be deactivated by using file.logPollInterval=NO.
  
  For loops that last 5 seconds or less, the output can be activated with file.logPollInterval=YES.
- file.processingMode=<
```
processingMode
```
  >
  Once the files' contents have been sent to the Integration Engine, specify how you want them to be processed.
  There are five possible processing types for
```
processingModedeletearchivearchiveWithTimestampsetAttributetest
```
  : , , , , or .
```
delete
```
  means that successfully processed files should be deleted.
```
archivearchiveWithTimestamp
```
  and mean that successfully processed files are moved to an archive directory.
  In
```
archive
```
  mode, the file name is copied unchanged. If a file with the same name already exists in the archive directory, it is overwritten.
  In the
```
archiveWithTimestamp
```
  mode, a time stamp including the date and time is added to the file name. The format of the time stamp is yyyyMMdd-hhMMss-SSS_, where yyyy specifies a year and SSS the number of milliseconds. As a result, files can be sorted according to the time they entered the archive directory, irrespective of the file name. This also stops files with the same name being overwritten.
  In the case of both processing types, the archive directory must be specified using the following parameters:
  - file.archiveDir=
```
<archiveDir>
```
    This parameter is mandatory for these processing types.
```
setAttribute
```
  means that successfully processed files are given the attribute read only. This means that only files you can write to are processed.
```
test
```
  means that successfully sent files will not be processed.
  Caution
  This means that files are sent again as a new message if the file/FTP adapter is restarted or if the time period specified in
  file.pollInterval
  is exceeded. This mode is exclusively of use when testing the configuration of the file/FTP adapter or the Integration Engine, and not for production operation.
The following specifications are not mandatory:
- file.processingLocked=
```
YES|NO
```
Specify here whether files that are locked by other applications are to be transferred or not. The default setting is
```
NOYES
```
, meaning that only files that are not locked are transferred. In particular, this ensures that the adapter does not transfer incomplete files that are generated or transferred by other applications. Only change the setting to if you can guarantee that such data losses will not occur.
- file.processingOrder=<
```
processingOrder>=byDate|byName
```
  Specify here the sequence in which files are to be processed if you used placeholders when you specified file.sourceFileName, and the system found multiple files to be processed.
  The default value is
```
byNamebyDate
```
  . This value means that files are processed in alphabetical order. Alternatively, you can specify . In this case, files are processed according to their time stamp in the file system, starting with the oldest file.
- file.messageAttributes=<name,directory>
  To save the name of the processed file and/or name of the directory that the file is from in the message header of the XI message, set this parameter.
  
  You can only save the file name or the directory name in the message header.
- file.emtpyFileStop=true|false
  Specify how empty files (length 0 bytes) found in the source directory are to be handled.
  
  The default value is false. If the adapter finds an empty file in the source directory then it is processed.
  
  Set the value to true and XI.QualityOfService=EOIO and an error message is created and the queue processing is stopped.
  
  Set the value to true and XI.QualityOfService=EO and the processing of the empty file is stopped and an error message is created. The empty file is deleted from the source directory and stored in a directory that you specify using the file.badMsgDirparameter.
- file.badMsgDir=<valid path to directory to collect empty files>
  Enter the path to the directory in which empty files are to be saved. A time stamp is added to each empty file that is stored in the directory. A script file is created for each empty file that is stored here.
  
  To copy a corrected file with its original name back to the source directory, click on the script file. The script file is then deleted automatically.
- 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.executeAfterAll=<operating system command>
  An operating system command specified here is executed once all files have been successfully processed that were found in a run. The default value is an empty character string (no command).
- file.encoding=<codepage>
  This parameter is used to import text files. The default setting is to use the system code page that is specific to the configuration of the installed operating system. You can find the system code page under file.encoding in the general system information of the About Adapter Engine menu option.
  
  You must specify the value UTF-8 for XML text documents that are coded in UTF-8. Text files that are neither in the system code page nor are coded in UTF-8 can only be read if the corresponding code page is available in the Java runtime environment. The file content is converted to the UTF-8 code page before it is sent.
  
  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

Note

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

Caution

XML text documents generally contain their own code page description and should be treated as binary data type.

If you select files from an FTP server and not from the file system, you need to make the following additional specifications:

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.sourceDir and file.sourceFileName then refer to the FTP server. The following are then not possible specifications:
- setAttribute for parameter file.processingMode.
- byDate for parameter file.processingOrder.
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.mode=<Binary|Text
```
>
```
This optional specification enables you to set the transfer mode of the FTP connection to either text or data transfer. The default value is the payload type of the received document from the Integration Server.

Specifications for the conversion to an XML document in mode
```
FILE2XMBWITHROWCONVERSION
```
If you set the sender file/FTP adapter mode to
```
FILE2XMBWITHROWCONVERSION
```
, a text file with identical structures of a type is expected that is arranged line-by-line by default. However, it is possible to specify other separators to separate structures. The structure can be converted to an XML document and sent to the Integration Engine in place of the original file. This conversion occurs in addition to all other processing described in previous sections.
The lines of the text file must either contain separators, or have columns of fixed length, or both. You can either specify column names explicitly in this segment, or they can be read as header lines from the file itself.

You cannot specify any additional metadata (such as column types or conversion rules for columns). Information of this type must be made available during mapping in the Integration Engine pipeline. When the sender file/FTP adapter converts non-XML to XML format, only an XML document for the mapping in the Integration Engine should be created.

Handling Structure Deviations

The conversion routine assumes that all structures are constant. The number of fields corresponds to the entry in parameter xml.fieldNames or the number and length of fields in parameter xml.fieldFixedLengths.

The structures are not validated. However, you can use the parameters described below to influence the way the conversion routine functions when structure deviations occur.

If you want to allow the structure found at runtime to differ from the configured structure, configure the xml.missingLastFields and xml.additionalLastFields parameters. If you do not use these parameters, the result of the conversion depends on whether you have configured the xml.fieldFixedLengthsparameter:
- Parameter xml.fieldFixedLengths not defined
  The number of fields in the inbound structure is defined by the value specified in xml.fieldSeparator:
  - If the inbound structure contains more fields than specified in xml.fieldNames, conversion is terminated with an error message.
  - If the inbound structure contains less fields than in xml.fieldNames, the conversion is executed.
    The fields are also missing in the XML structure
- Parameter xml.fieldFixedLengths defined.
  - If the inbound structure contains more fields than in xml.fieldNames or xml.fieldFixedLengths the conversion is executed.
    Additional fields in the structure are ignored.
  - If the inbound structure contains less fields than specified in xml.fieldNames, conversion is terminated with an error message.
    If the last field only is shorter than defined or is missing completely, the conversion is executed. The contents of the last field are then applied to the XML element as found. Consequently, the value can be incomplete or empty.
You can change this behavior by using the parameters xml.missingLastFields and xml.additionalLastFields. If you use this parameter, you can perform a defined check on the inbound structures, and well-defined source structures are created.

Note
You can implement some of the functions of this parameter by using the xml.lastFieldsOptional parameter.

xml.lastFieldsOptional is however obsolete and must not be used.

If you use the parameter together with the xml.missingLastFields and xml.additionalLastFields parameters an error message is displayed at runtime.

The following mandatory arguments refer to the mode

FILE2XMBWITHROWCONVERSIONFILE2XMB

. In mode , none of the following arguments should be set; existing arguments are ignored.

Make the following specifications:

xml.processFieldNames=
Specify the field names. You can enter the following:
- ```
notAvailable
```
  means that no field name information is available.
```
notAvailable
```
  means that no field name information is assumed to be in the configuration or in the file to be converted. In this case, the columns in the XML document are identified using a simple counter tag (<columnX> , X=0,1,2…).
- ```
fromFile
```
  means that the field name information is located in the header line of the file to be converted.
- ```
fromFileWithBlankLinefromFile.
```
  corresponds to After the header line there also follows a blank line or separator that is skipped.
- ```
fromConfigurationxml.fieldNames=
```
  means that no header information exists in the file to be converted, but it will be delivered by the present configuration. You must set the value for correspondingly for this (see below).
This specification is mandatory.
xml.fieldFixedLengths=
If you make a specification here, the system expects a character string that contains the lengths of the file columns as arguments separated by commas. If you also specify a separator for the columns, you must not add its length to the length of the columns.

If you do not make any specifications for xml.fieldSeparator=, the specification xml.fieldFixedLengths= is mandatory.
xml.fieldSeparator=
If you make a specification here, the system expects that the file contains the specified character string (one or more characters) as a separator between the individual columns.

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

If you made a specification for fieldFixedLengths=, the extra length of the separator is taken into account, but no further consistency checks are performed.

Note
You must specify at least either xml.fieldFixedLengths orxml.fieldSeparator.
xml.lastFieldsOptional=
```
YES|NO
```
(veraltet)
This parameter specifies whether the last fields can be omitted (
```
YESNONO
```
) or not () in a structure with fixed field lengths as defined in the parameter xml.fieldFixedLengths. If you do not make a specification, the default value is .
The parameter does not work for CSV structures, missing fields are simply ignored.
xml.keepIncompleteFields=
```
YES|NO
```
(veraltet)
This parameter is only evaluated if you enter a value for xml.fieldFixedLengths.
- If you enter
```
NO
```
  and the last field found in the structure is shorter than specified in xml.fieldFixedLengths, processing is terminated with a corresponding error message.
  This is the default.
- If you enter
```
YES
```
  , the last field found in the inbound structure is transferred to the outbound structure, even if it is shorter than specified in xml.fieldFixedLengths.
  Note
  You use this parameter to control the behavior of the conversion routine for the last field in a structure.
  
  Use the xml.missingLastFields parameter to define the behavior at runtime when the structure contains less fields in total that specified in xml.fieldFixedLengths.
xml.enclosureSign=
You can specify a string here that acts as a text delimiter. Text enclosed by such delimiters is transferred to the target structure unchanged, although the default setting is to remove all text delimiters. Separators within such texts are ignored.

This parameter is optional. The default setting is an empty value (no text delimiter).
xml.enclosureSignEnd=
If there are different text delimiters for the beginning and the end of a text, here you can specify the text delimiter for the end of the text. If you do not enter a value, the value from xml.enclosureSignis used instead.
xml.enclosureSignEscape=
Here you can specify a string that replaces the text delimiter if it occurs within a text that it delimits. When the text is transferred the string is replaced by the value specified in xml.enclosureSign. The default setting is no value.
xml.enclosureSignEndEscape=
Specify a string that replaces the text delimiter for the end of the text if it occurs within a text that it delimits. When the text is transferred the string is replaced by the value specified in xml.enclosureSignEnd. The default setting is no value.
xml.enclosureConversione=
```
YES|NO
```
This value specifies whether the text delimiter is to be removed or whether the escape character is to be replaced when the files are transferred. The default setting is
```
YESNO
```
; if you change the setting to , all characters are transferred unchanged.
Tip
If you specify xml.enclosureSign=" and xml.enclosureSignEsc="", text enclosed in quotation marks is transferred unchanged and the quotation marks are removed.

If the escape character for a quotation mark ("") itself occurs in the text it is replaced by the quotation mark during the transfer.
xml.endSeparator=
If you want to define an additional character string as a separator after the last column in a row, make a specification here. The system skips this separator when it processes the last column (otherwise the system would treat it as part of the last column).

The default value is a line break (no explicit separator after the last column). Instead, the structures are arranged line-by-line.
xml.beginSeparator=
If you want to define an additional character string as a separator before the first column in a row, make a specification here. The system skips this separator when it processes this column (otherwise the system would treat it as part of the first column).

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.beginSeparatorxml.endSeparator0xHH´HH
```
and ), you can specify non-printable ASCII characters. These characters can each be inserted individually in the string in the form ´(including the quotation marks), where represents the character encoded as a hexadecimal value.
Note
Inserting Strings for Separators in the XML Document:

The separators specified with xml.beginSeparator and xml.endSeparatorcan also be inserted as fields in the structure of the generated XML document. To do this, specify field names with the following entries:

xml.addBeginSeparatorAsField=<fieldname>

and/or

xml.addEndSeparatorAsField=<fieldname>

The strings, together with the specified field name, are then inserted either at the start or the end of the structure, as they were specified in xml.beginSeparator and xml.endSeparator. The definition of special characters also needs to be included. Special characters cannot be converted since characters of this type are not permitted in XML documents.
xml.fieldNames=
If you specified fromConfiguration forprocessFieldNames=, this specification is mandatory. The system expects a list of the column names. The format of these column names varies depending on the following specifications:

If you specify a value for xml.fieldFixedLengths=, the system expects a string that contains the names of the file columns as arguments separated by commas (this is also true if you specify a value for xml.comlumnSeparator=).

If you only specify a value for xml.fieldSeparator=, the system expects a string that contains the names of the file columns in the same format as the file rows. This means that the same separator string and any additional strings you specify for xml.endSeparatorand/or xml.beginSeparator are expected.
xml.fieldContentFormatting=trim|nothing
If you specify trim (the default setting), all blanks that proceed and follow a found value are removed.
If you specify
```
nothing
```
, the value remains unchanged.
xml.structureTitle=<anyName>
The value you specify here is used as the name of the structure in the XML schema. The default is
```
row
```
.
xml.documentName=<name>
If you specify a document name, it is inserted in the message as the main XML tag. The default setting is
```
resultset
```
.
xml.documentNamespace=<namespace>
If specified, the namespace is added to the name of the document.

Use the following parameters if you want to influence the behavior of the conversion routine for inbound structures that deviate from the configuration.

xml.missingLastFields=ignore|add|error
If the inbound structure has less fields than specified in the configuration then the XML outbound structure is created as follows:
- ignore
  Outbound structure only contains the fields in the inbound structure
- add
  Outbound structure contains all fields from the configuration; the fields missing in the inbound structure are empty.
- error
  Conversion is terminated due to the incomplete inbound structure. An error message is displayed.
xml.additionalLastFields=ignore|error
If the inbound structure has more fields than specified in the configuration then the XML outbound structure is created as follows:
- ignore
  Outbound structure only contains the fields in the inbound structure
- error
  Conversion is terminated due to the incomplete inbound structure. An error message is displayed.
The default value is
```
ignoreerror
```
. If you have defined the xml.fieldFixedLengths parameter, the default value is .
Note
If you have defined the xml.fieldFixedLengths parameter and do not set either of the parameters described above, apart from the default values, the conversion routine works the same as described under Handling Structure Deviations.

Only once you set one of the two parameters will the other parameter be evaluated with its default value.

To ensure a well-defined runtime behavior for variable inbound structures, SAP recommends that you always set both parameters.

The document constructed from the specifications described looks as follows:

<field-name1>field-value</field-name1>

<field-name2>field-value</field-name2>

<field-name3>field-value</field-name3>

</structureTitle>

<field-name1>field-value</field-name1>

<field-name2>field-value</field-name2>

<field-name3>field-value</field-name3>

</structureTitle>

</documentName>

A document of this type cannot be processed further by the Integration Engine.

Specifications for the conversion to an XML document in mode
```
FILE2XMBWITHSTRUCTURECONVERSION
```
)
In this mode, you can convert text files with more complex file structures to an XML output format. The files contain various row formats in logical structures.

The system expects a file with one or more logical structures (Recordsets). An unlimited number of recordsets (from one to all recordsets in the file) can be sent to the Integration Engine as separate messages.

A recordset can contain multiple types of substructures identified by logical names. There can be a fixed or variable number of substructures in a recordset. The format of a substructure of this type is fixed and corresponds to the description of the line format in step 7. A substructure must always be represented in exactly one line of the text document.
- Specifications for Recordsets:
  - xml.recordsetStructure=<NameA,nA,nameB,nB,…>
    This string specifies the sequence and number of substructures (identified by logical names).
    nA=1,2,30
    ,… or * (for a variable, unlimited number, including ). The same is the case for nB, and so on.
  - xml.recordsetName=<tagName>
    The value you specify here is used as the name of the structure in the XML schema. The default is
    Recordset
    .
  - xml.recordsetNamespace=uri
    If specified, this is added to the name of the recordset.
  - xml.recordsetsPerMessage=<noOfRecordsets>
    1,…, *
    for an entire document in a message.
    Specifies the number of recordsets to be grouped together for one message. If the number of recordsets in a document is greater than the number specified, the adapter creates multiple messages from a document. The last of these messages might then contain fewer recordsets than specified.
    
    If you specify Exactly Once as the quality of service, each of these messages (that is to say, each part of a document from which a message is created) is sent to the Integration Engine exactly once. This is also true if the application is interrupted while creating the messages and restarted again later.

If you change the file containing the document before the application is restarted, the file is treated as new. Any outstanding Exactly Once messages can no longer be sent for this file.

xml.documentName=<name>
This specification is mandatory if you set recordsetsPerMessage to a value greater than
```
1*
```
or .
If you specify a document name, it is inserted in the message as the main XML tag. If the generated message comprises more than one recordset, then this specification is mandatory since an XML document must contain exactly one main tag.
xml.documentNamespace=<namespace>
If specified, the namespace is added to the name of the document.
xml.documentSkipFirstRows=<noOfRows>
Specifies how many lines are to be skipped at the start of the document. The default is
```
0
```
.
xml.keyFieldName=<fieldname>
If you specified a variable number of substructures for xml.recordsetStructure (at least one substructure with a the number '*' ), the substructures must be identified by the parser from their content. This means that a key field must be set with different constants for the different substructures.

In this case, you must specify a key field and the field name must occur in all substructures.

If a structure has a fixed number of substructures, this specification is ignored.
xml.keyFieldType=CaseSensitiveString|CaseInsensitveString|Integer|Float
If you specify a key field, then you must also specify its type. The comparison with the specified values is based on this key field type (see xml.NameA.keyFieldValue= below).
xml.recordsetStructureOrder=asc|var
The start and end of recordsets containing a variable number and arrangement of structures are determined as follows:

If the value is asc (ascending), the order of the recordset structures is assumed to be fixed. A new recordset is started as soon as an earlier structure occurs.

If the value is var (variable), the order is not assumed to be fixed. A new recordset is only started when another structure occurs that is defined with a fixed number. If all structures are defined as variable (*), the system interprets the entire document as a single recordset.

The default value is asc.

Specifications for Substructures:
Use the same specifications you made in step 7 and add the name of the substructure to the name of the respective property, separated by a period after the XML prefix.
Tip
```
xml.NameA.fieldNamesxml.fieldNames
```
instead of to specify the field names of substructure NameA.
Changes to the properties in step 7:
- xml.NameA.structureTitle=<anyName>
  The default is not
```
rowNameA
```
  here, but the structure name from xml.recordsetStructure. So the default is .
- xml.NameA.processFieldNames=
  You do not need to make any specifications here since this property is defined by
```
fromConfiguration
```
  in this mode. This means that the definition of the substructure must be contained in the configuration file. No structure information can be transferred in the file itself.
- xml.NameA.fieldNames=<listOfFieldnames>
  This specification is mandatory for the aforementioned reasons.
- xml.NameA.keyFieldValue=<valueInSubstructureName>
  This specification is also mandatory if you set xml.keyFieldName= in the recordset definition.
- xml.NameA.keyFieldInStructure=add|ignore
  Here you can specify whether the key field of the substructure should be added to the XML document (
```
addignoreadd
```
  ) or ignored (). The default is .
- xml.NameA.endSeparator=
  Even if no specification is made here, a line break must follow since substructures are always expected as a line of the document.

The document constructed from the specifications described looks as follows:

<documentName>...

<NameA>

<field-nameA1>field-value</field-nameA1>

<field-nameA2>field-value</field-nameA2>

<field-nameA3>field-value</field-nameA3>

</NameA>

<NameB>

<field-nameB1>column-value</field-nameB1>

<field-nameB2>column-value</field-nameB2>

<field-nameB3>column-value</field-nameB3>

</NameB>

</recordset>

...

...

</recordset>

</documentName>...

The tag <documentName> is completed if you made a specification for xml.documentName=. If the message contains more than one recordset, this specification is mandatory. The number of recordsets is in turn dependent on the specification made for xml.recordsetsPerMessage.

A document of this type cannot be processed further by the Integration Engine.

Transport of further documents within a message to the Integration Engine
You have the option of transporting additional file contents within a message to the Integration Engine. The following rules apply for this procedure:
- The files must all be in the same directory that is defined in file.sourceDir.
- The files that are to be transported are grouped together using their file name, which must be identical except for one defined part (for example, the suffix).
- Additional file contents can only be transported unchanged, in other words, without the conversion options described in points 5 and 6.
- Messages of this type with multiple payloads require a corresponding receiver that can process them.
To add additional file contents, you must make the following specifications:
- XI.AdditionalPayloads=<NameA, NameB, …>
  This specification defines a logical name for each additional file that is then used in the subsequent parameters.
- file.NameA.namePart=<"Main-NamePart"="Additional-NamePart">
  This specification specifies which part of the original file name is to be replaced to create the name of the additional file.
  Note
  The following example explains how three files of type text, pdf and doc are included in a message:
  file.sourceFileName=
  x*.txt
  The files x1.txt and x2.txt were found in the specified directory following this specification.
  
  XI.AdditionalPayloads=addaPDF, addaDOC
  
  file.addaPDF.namePart=".txt"=".pdf"
  
  file.addaDOC.namePart=".txt"=".doc"
  
  The files x1.pdf and x1.doc were also searched for in the same directory as the file x1.txt. The contents of these three files are included in a message to the Integration Engine. Likewise, the files x2.pdf and x2.doc are searched for and processed like file x2.txt.
- file.NameA.optional=YES|NO
  Specify here whether the additional file is required or whether it is optional. If the file is not found for
```
NOYESYES
```
  , the action is terminated with an error message. For , the specification is ignored and the message sent to the Integration Engine without the additional file contents. The default is .
- file.NameA.type=BIN|TXT
  Specifies the document data type.
  The default value is
```
BIN
```
  .
How the adapter responds when it is stopped.
file.stopMode=0|1|2
- 0Processing is terminated immediately if the adapter is stopped.
- 1 If a file is still being processed, then processing is completed before the adapter is stopped.
- 2 All files in the current file list are processed. Only then is the adapter stopped.
The default value is
```
0
```
.