Configuring the Inbound File Adapter
Use
You need to configure the inbound file adapter to send file contents to the
Integration Engine.To configure the adapter you must specify the following:
Prerequisites
You have:
Procedure
The configuration of the inbound file adapter comprises five functional subareas:
Specify the class name as follows:
classname=com.sap.aii.messaging.adapter.ModuleFile2XMB
This specification is mandatory.
Specify the mode of the inbound file adapter. The following values are permitted:
The content of the file is sent directly to the Integration Engine.
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 5.
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 6.
A special file format is expected here that represents a completely serialized Integration Engine message. This file format can be generated from the
outbound file 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 3. Therefore, only parameters required for logging on to the Integration Engine (namely, XMB.TargetURL, or XMB.User, XMB.Password, XMB.Client and XMB.Language) are evaluated from the configuration in this mode.The default value is
FILE2XMB.Enter the complete address (URL) of the Integration Engine that you want to send the message to:
XMB.TargetURL=http://IntegrationEngineHost:port/pipeline-arguments
This specification is mandatory.
The Integration Engine address can also be accessed dynamically from the System Landscape Directory. The following entry is added to the configuration for this purpose:
XMB.SLDConfiguration=SLDaccessor
In this case, for the system specified with
XMB.SenderBusinessSystem, the URL of the corresponding Integration Server in the SLD is exported and the value specified under XMB.TargetURL is used instead. You also need to specify the following:XMB.TargetURL=<fromSLD>
To be able to access the System Landscape Directory, the
SLDaccessor service must be configured correspondingly and the respective entries must be maintained in the System Landscape Directory.If an authentication was specified for the specified URL (HTTP service) in the Integration Engine, the following specifications are mandatory:
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 you use a different client or language to the default setting in the Integration Engine when logging on, you can also set the following parameters:
The following arguments are mandatory, expect in
FILE2XMBSTREAM mode. They are used to identify the adapter configuration in routing and in mapping in the Integration Engine pipeline. You can also find an explanation about each argument there.
The receiver system can also be changed through routing in the Integration Engine. This specification is then not mandatory.
Specifies the document type that is sent to the Integration Engine. The following values are permitted:
type=text/xml
For XML texts
type=application/xml
For binary data
type=text/plain
For non XML texts
Specifies the document data type. The following values are permitted:
kind=B
(Binary data type)kind=T
(Text data type)The default value is
T.Specifies how the Integration Engine should process a message. The following values are permitted:
XMB.QualityOfService
=BE (Best Effort: means synchronous processing)XMB.QualityOfService
=EO (Exactly Once: means asynchronous processing with guaranteed execution exactly once)XMB.QualityOfService
=EOIO (Exactly Once in Order: means asynchronous processing using queues. This means guaranteed execution exactly once following the sequence of successive messages)This specification is mandatory.
You must also define a queue name for
EOIO:This queue name is used in the Integration Engine to process messages in the same sequence that they arrived in.
The following specifications are mandatory:
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.
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.
Specify the number of seconds that the adapter must wait if no files for processing can be found.
You can set the value to
0, if you do not want to repeat the call. In this case the adapter status remains as STARTED. To initiate a new call, choose Stop/Start or Restart to restart the adapter.Details regarding joining the queue are entered in the adapter log by default (
file.pollInterval>0). If the queue is short, this can lead to a correspondingly large amount of output in the log. In such instances, the log output (but not the queue itself) can be deactivated by using file.logPollInterval=NO.The default value is
YES.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
processingMode: delete, archive, archiveWithTimestamp, setAttribute or test.delete
means that successfully processed files should be deleted.archive
and archiveWithTimestamp 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 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.
This means that files are sent again as a new message if the file 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 adapter or the Integration Engine, and not for production operation.The following specifications are not mandatory:
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
byName. This value means that files are processed in alphabetical order. Alternatively, you can specify byDate. In this case, files are processed according to their time stamp in the file system, starting with the oldest file.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).
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).
If you select files from an FTP server and not from the file system, you need to make the following additional specifications:
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.sourceDir and file.sourceFileName refer to the FTP server. You cannot make the following specifications:setAttribute
for parameter file.processingMode.byDate
for parameter file.processingOrder.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).
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.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.If you set the inbound file adapter mode to
The rows 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 meta data (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 inbound file adapter converts non-XML to XML format, only an XML document for the mapping in the Integration Engine should be created.
The following mandatory arguments refer to the mode
FILE2XMBWITHROWCONVERSION. In mode FILE2XMB, none of the following arguments should be set; existing arguments are ignored.Make the following specifications:
Specify the field names. The following are possible specifications:
notAvailable
means that no field name information is available.fromFile
means that the field name information is located in the header line of the file to be converted.fromFileWithBlankLine
corresponds to fromFile. After the header line there also follows a blank line or separator that is skipped.fromConfiguration
means that no header information exits in the file to be converted, but it will be delivered by the present configuration. You must set the value for xml.fieldNames= correspondingly for this (see below).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 ).This specification is mandatory.
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.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.
You must specify at least either
xml.fieldFixedLengths or xml.fieldSeparator.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.
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).
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 be 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.
Inserting Strings for Separators in the XML Document:
The separators specified with
xml.beginSeparator and xml.endSeparator can also be inserted as fields in the structure of the generated XML document. To do so, specify field names with the following specifications: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.If you specified
fromConfiguration for processFieldNames=, 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.endSeparator and/or xml.beginSeparator are expected.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.The value you specify here is used as the name of the structure in the XML schema. The default is
row.The document constructed from the specifications described looks as follows:
<resultset>
<structureTitle>
<field-name1>field-value</field-name1>
<field-name2>field-value</field-name2>
<field-name3>field-value</field-name3>
</structureTitle>
<structureTitle>
<field-name1>field-value</field-name1>
<field-name2>field-value</field-name2>
<field-name3>field-value</field-name3>
</structureTitle>
</resultset>
A document of this type cannot be processed further by the Integration Engine.
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 5. A substructure must always be represented in exactly one line of the text document.
Specifications for Recordsets:
This string specifies the sequence and number of substructures (identified by logical names).
Therefore,
nA=1,2,3, or * (for a variable, unlimited number, including 0). The same is the case for nB, and so on.The value you specify here is used as the name of the structure in the XML schema. The default is
Recordset.If specified, this is added to the name of the recordset.
1, , *
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.
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.
If specified, the namespace is added to the name of the document.
Specifies how many rows are to be skipped at the start of the document. The default is
0.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.
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).Specifications for Substructures:
Use the same specifications you made in step 5 and add the name of the substructure to the name of the respective property, separated by a period after the XML prefix.
xml.NameA.fieldNames
instead of xml.fieldNames to specify the field names of substructure NameA.Changes to the properties in step 5:
The default is not
row here, but the structure name from xml.recordsetStructure. So the default is NameA.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.This specification is mandatory for the aforementioned reasons.
This specification is also mandatory if you set
xml.keyFieldName= in the recordset definition.Here you can specify whether the key field of the substructure should be added to the XML document (
add) or ignored (ignore). The default is add.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>...
<recordset>
<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>
...
</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.
You have the option of transporting additional file contents within a message to the Integration Engine. The following rules apply for this procedure:
To add additional file contents, you must make the following specifications:
This specification defines a logical name for each additional file that is then used in the subsequent parameters.
This specification specifies which part of the original file name is to be replaced to create the name of the additional file.
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.XMB.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.Specify here whether the additional file is required or whether it is optional. If the file is not found for
YES, the action is terminated with an error message. For NO, the specification is ignored and the message sent to the Integration Engine without the additional file contents. The default is YES.Specifies the document type that is sent to the Integration Engine. The following values are permitted:
type=text/xml
(for XML texts)type=application/xml
(for binary data)type=text/plain
(for non-XML texts)Specifies the document data type. The following values are permitted:
kind=B
(Binary data type)kind=T
(Text data type)The default value is
T.