Odette FTP Queue Handler Service
The Odette FTP Queue Handler service queues a file for sending by adding entries to the process queue and to an associated Mailbox.
The following table provides an overview of the Odette FTP Queue Handler service:
Category | Description |
---|---|
System name | Odette FTP Queue Handler Service |
Graphical Process Modeler (GPM) category | All Services |
Description | The Odette FTP Queue Handler is used to queue a file for sending by adding entries to the process queue and to an associated Mailbox, if used. These entries contain all information required by the Odette FTP adapter to identify the Physical Partner Contract and prepare a file for sending, for example, the Sterling B2B Integrator document or MessageID, Logical Partner Contract, and OFTP file name. In OFTP 2.0, a file can be compressed, encrypted, and signed in a CMS enveloped before it is persisted into the Odette FTP Message Queue. In DECIPHER Mode, an enveloped file in the Odette FTP Message Queue can be decrypted and written into the process data for further processing (same applies for compressed or signed files). |
Business usage | Use the Odette FTP Queue Handler to put a file into the send queue for a partner. The queue includes all the File, End to end Response (EERP) and Negative End Response (NERP) items in the process history with a status that indicates the item needs to be sent or resent. The file can be a document in a business process or a message in the partner mailbox. In DECIPHER Mode, an encrypted file in the Odette FTP Message Queue can be decrypted and written into the process data for further processing (the same applies for compressed and signed files). |
Usage example | There is a preconfigured instance of the Odette
FTP Queue Handler service named OFTPQueueHandler. Three business process
templates are provided to put items in the send queue:
|
Preconfigured? | Yes - OFTPQueueHandler |
Requires third-party files? | No |
Platform availability | All supported platforms for Sterling B2B Integrator |
Related services | Odette FTP Scheduler serviceOdette FTP adapter (Sterling B2B Integrator Scheduler) |
Application requirements | The Odette FTP Queue Handler service is used with the Odette FTP adapter in the Sterling B2B Integrator Scheduler. |
Initiates business processes? | No |
Invocation | This service is invoked from a business process. |
Business process context considerations | A message can be queued for sending in two different
ways:
|
Returned status values | Possible values:
|
Restrictions | None |
Persistence level | System default |
Testing considerations | Not applicable |
mode | The WFC parameter "mode" determines whether the Odette FTP Queue Handler works in
"QUEUE" mode or "DECIPHER" mode. Valid values:
|
Configuring the Odette FTP Queue Handler Service in Queued Mode
There are no configurable service instance parameters for the Odette FTP Queue Handler service.
If Odette FTP version 2.0 is used, the OetteFTP Queue Handler service is optionally responsible for signing, encrypting and compressing files before queueing them.
- Create an Odette FTP Partner Profile.
- Create the following XML structures in a business process.
- Pass the XML structures to the Odette FTP Queue Handler service from the business process.
Input XML Structures
To put files, EERPs or NERPs into the OFTP queue, the Odette FTP Queue Handler service requires the following XML input structures which have to be passed to the Service from a business process:
XML Input Structure for Message Type FILE:
<OFTPDataItem>
<FILE>
<properties>
<LogicalPartnerContract>log_partner_name</LogicalPartnerContract>
<!-- LogicalPartner Properties overriding defaults in partner
profile -->
<OFTPVirtualFilename>virtual_filename</ OFTPVirtualFilename>
<Date>date</Date>
<Time>time</Time>
<FileFormat>[U|T|V|F]</ FileFormat>
<OFTPFileUserField>free_user_content</ OFTPFileUserField>
<RecordLength>n<RecordLength>
<RecordDelimiter>one_or_two_delimiters<RecordDelimiter>
</properties>
<document>
<MessageID>message_id<MessageID
_OR_
<PrimaryDocumentSCIObjectID="document_id_1"/>
</document>
<FILE>
</OFTPDataItem>
Defining XML Node Name Parameters
- Make the following changes to the XML structure.
The following table describes the parameters that need to match the definitions in the OFTP partner profile. Make sure that all required parameters belonging to your logical and physical contract are configured correctly, including all parameters of the logical and physical partners referenced in the contract part. Details are described in the default partner profile in XML comments.
Parameter Description LogicalPartnerContract The unique name of the logical partner contract as defined in the Partner Profile. This is an 80-character string. Required. OFTPVirtualFilename The OFTP Virtual File name. Defined according to the bilateral agreement with your trading partner. This is a 26-character string. Optional. If omitted, a default file name is taken from the partner profile contract. Note: The virtual file name, date, and time are used to uniquely define a file.Date The date tag used to send the message. This is a six-digit or eight-digit number. Format is as follows: - YYMMDD (used for version1.2 and version 1.3)
- YYYYMMDD (used for version 1.4 and higher)
Note: The virtual file name, date, and time are used to uniquely define a file.Time The time stamp from when a file is made available for transmission at the sender's location. This is a six-digit or ten-digit number. Format is as follows: - HHMMSS (used for version 1.2 and version 1.3)
- HHMMSS<four-digit counter> (used for version 1.4 and higher)
FileFormat This field specifies the format of the virtual file. Valid values are:U - unstructured binary fileT - text fileF - fixed-length record binary fileV - variable-length record binary fileOptional. If specified, overrides value in the partner profile. OFTPFileUserField Used as defined by your bilateral agreement with your partner. Optional. If specified, overrides value in the partner profile. RecordDelimiter Depending on File Format: One or two record delimiters (decimal numbers of Character code, for example, 13,10 for <CR>>LF> (Windows) or 10 for <LF> (UNIX). - File Format " Unstructured Binary file" ("U") / "text" ("T"):
Data is not split up in records. Delimiters are not used. In the OFTP Partner Profile database, both Record Delimiters are set to (-1,-1).
- File Format "Variable format binary file" ("V"):
Data is split up in records separated by one or optionally two record delimiters.
Specify one or two delimiters as decimal values. Specify -1,-1 to use Operating
system dependent default delimiter (13,10 for Windows and 10 for UNIX)
- File Format "Fixed Format binary file":
Data is split up in records of length.
For Format "F" there are following specified cases:
RecordLength Number of bytes to be transferred in one OFTP record. Applies only to FileFormat = F. Optional. If specified, overrides value in the partner profile. MessageID The unique number identifying the message in the partner mailbox. Specify either MessageID or PrimaryDocument, not both. PrimaryDocument The Sterling B2B Integrator document to send. Specify either MessageID or PrimaryDocument, not both.
XML Input Structure for Message Type EERP
The following is an example of the input structure for an EERP:
<OFTPDataItem>
<EERP>
<properties>
<LogicalPartnerContract>log_partner_name</LogicalPartnerContract>
<OFTPVirtualFilename>virtual_filename</ OFTPVirtualFilename>
<Date>date</Date>
<Time>time</Time>
</properties>
<EERP>
</OFTPDataItem>
Parameter | Description |
---|---|
LogicalPartnerContract | The unique name of the logical partner contract as defined in the Partner Profile XML file. This is an 80-character string. Required. |
OFTPVirtualFilename | The OFTP Virtual File name. Defined according to
the bilateral agreement with your trading partner. This is a 26-character
string. Required. If omitted a default file name is taken from the
partner profile contract. Note: The virtual file name, date, and time
are used to uniquely define a file.
|
Date | The date tag used to send the message. This is
a six-digit or eight-digit number. Format is as follows:
Note: The virtual file name, date, and time are used
to uniquely define a file.
|
Time | The time stamp from when a file is made available
for transmission at the sender's location. This is a six-digit
or ten-digit number. Format is as follows:
Note: The virtual
file name, date, and time are used to uniquely define a file.
|
XML Input Structure for Message Type NERP
The following is an example of the input structure for an NERP:
<OFTPDataItem>
<NERP>
<properties>
<LogicalPartnerContract>log_partner_name</LogicalPartnerContract>
<Creator>creator_of_nerp</Creator>
<OFTPVirtualFilename>virtual_filename</ OFTPVirtualFilename>
<Date>date</Date>
<Time>time</Time>
<Reason>reasoncode</Reason>
</properties>
<NERP>
</OFTPDataItem>
Parameter | Description |
---|---|
LogicalPartnerContract | The unique name of the logical partner contract as defined in the Partner Profile XML file. This is an 80-character string. Required. |
Creator | Creator of the NERP. This is a 25-character string. Required. |
OFTPVirtualFilename | The OFTP Virtual File name. Defined according to
the bilateral agreement with your trading partner. This is a 26-character
string. Required. Note: The virtual file name, date, and time are
used to uniquely define a file.
|
Date | The date tag used to send the message. Required.
This is a six-digit or eight-digit number. Format is as follows:
Note: The virtual file name, date, and time are used to uniquely
define a file.
|
Time | The time stamp from when a file is made available
for transmission at the sender's location. Required. This is
a six-digit or ten-digit number. Format is as follows:
Note: The virtual file name, date, and time are used to uniquely
define a file.
|
Reason | Reason code for the NERP. Required. Valid values are two-digit numbers defined in the OFTP 2.0 specification. |
Decipher Mode
To decrypt an encrypted OFTP file in a Primary Document or Mailbox (specified by Message Id) the Odette FTP Queue Handler has to be called in DECIPHER mode and compressed or signed. The following example shows the usage of the Queue Handler for this purpose:
<!--
Adapter : OdetteFTP Queue Handler - DECIPHER mode
Description : Example template process for decrypting a received encrypted
file. This process can be used in the business process
which is started for inbound files.
Prerequisites: - Read the OdetteFTP Queue Handler documentation
- Configure and enable the OdetteFTP Adapter instance
"OFTPQueueHandler"
- Modify this template process as described in the
comments below.
- Make sure OFTP Partner Profile has been imported
into the database.
Input : Parameter
mode DECIPHER Either MessageId <number>
Queue Handler searches for an file entry in the Odette FTP Queue
with Message ID <number>. If there is a file it is decrypted. or
PPrimaryDocument. Pass PrimaryDocument which needs to be decrypted
in the process data. -->
<process name="oftpdecrypt">
<sequence name="decrypt">
<!--
Either pass parameters from an initiating process and remove the assign
statements _or_ enter the values in the following assign statements.
Note: If you use DocumentId, you must also use FileProcessing and
Response_DOC_ID.
-->
<assign to="mode" from="'DECIPHER'" />
<!--
<assign to="MessageId">number</assign>
-->
<!--
<assign to="DocumentId">number</assign>
<assign to="FileProcessing">true</assign>
<assign to="Response_DOC_ID">docid_from_oftp_object</assign>
-->
<!-- Decipher document -->
<operation name="DecryptFile">
<participant name="OFTPQueueHandler" />
<output message="OFTPOut">
<assign to="." from="*"/>
</output>
<input message="OFTPIn">
<assign to="." from="*"/>
</input>
</operation>
</sequence>
</process>
In Manual Mode the Odette FTP Queue Handler could be called in DECIPHER mode directly from the business process initiated for an encrypted inbound file.
In Queued Mode an Automated Mailbox rule could be used to initiate a business process for inbound files calling the Odette FTP Queue Handler in DECIPHER mode.
Error Messages (both Queued and Decipher modes)
Advanced Status | Description |
---|---|
OFTP_INITIALIZATION_FAILED | An error occurred when initializing required components used in the Service. For example, the Service Framework providing logging services did not start successfully or the configuration of the Partner Profile contained errors. See Odette FTP.log for details. |
QUEUE_DATAITEM_FAILED | Either the Input XML structure is invalid (syntax errors, missing fields, invalid field length) or errors occurred when storing the entry in the process queue (table OFTP Object). See Odette FTP.log for details. |
Odette FTPQueueHandler_FAILURE | A general error occurred during processing that does not fit into the categories listed above. The reason is noted in the status report/Odette FTP.log. |
Error Codes for Decipher Mode
Error Code | Description |
---|---|
NO_PD_FOUND | DECIPHER mode. Processed data where no primary document could be found. Pass a primary document to the service. |
NO_ENCRYPTED_FILE_FOUND | DECIPHER mode. Either a primary document is found in process data, but an entry with document ID could not be found in the FTP_OBJECT table, or there is no entry in the OFTP_OBJECT table with the Message Id passed to the service. |
WRONG_OFTP_OBJECT_VERSION | DECIPHER mode. The file in the OFTP_OBJECT table is not received with the required OFTP Version 2.0. |
DOCUMENT_NOT_ENVELOPED | DECIPHER mode. A file in the OFTP_OBJECT table is found but it is has no CMS envelope. Parameter SFIDENV in OFTP_OBJECT_EXT is not "1"). |