Odette FTP Adapter
The Odette FTP adapter exchanges files with trading partners by using the Odette FTP protocol.
The following table provides an overview of the Odette FTP adapter:
Category | Description |
---|---|
System name | Odette FTP Adapter |
Graphical Process Modeler (GPM) category | All Services |
Description | This adapter is used to exchange files with trading
partners using the Odette FTP (OFTP) protocol. There are two modes
of operation:
|
Business usage | The Odette FTP adapter supports point-to-point or VAN-like communication between trading partners using the OFTP protocol version 1.2, version 1.3, version 1.4, or version 2.0 over ISDN or TCP/IP as an underlying communication protocol. Version 2.0 supports a secure and authenticated communication between trading partners with the ability to encrypt and digitally sign message data, request signed receipts, and provide data compression. Trading partners can securely exchange business documents in two directions-- as the receiver or as the initiator of the document (in a push/pull fashion) while maintaining the integrity, authentication, and the origin of the document. |
Usage example | Queue Handler Mode
|
Preconfigured? | No. For manual mode, there is an Odette FTP adapter instance named OFTPSendFile which is used for the preconfigured business processes oftpin and oftpout. Configure the OFTPSendFile instance prior to using it. |
Requires third-party files? | No, the Odette FTP adapter implements the complete OFTP and CAPI/IP protocol stack. |
Platform availability | All platforms supported by Sterling B2B Integrator |
Related services | Sterling B2B Integrator Scheduler and Odette FTP Scheduler service Odette FTP Queue Handler service |
Application requirements | For all modes and communication protocols:
|
Initiates business processes? | For each inbound message or receipt a business process is started. Create another business process oftpin for inbound files (Manual Mode). |
Invocation | Manual Mode: A business process initiating the Odette FTP Adapter manually or by a previous business process. Queue Handler Mode: The Odette FTP adapter is initiated by the Sterling B2B Integrator Scheduler service based on a partner-specific schedule. It can also be initiated by inbound communication from a trading partner. |
Business process context considerations | Queue Handler Mode: This is the recommended mode. The Queue Handler Mode can also be initiated manually. All messages are queued in the Odette FTP message queue in the partner mailbox. Manual Mode: Directly queued. The adapter takes one or more Primary Documents within the OFTPDataSet XML Input structure from the workflow. |
Returned status values | Returned status values:
|
Restrictions | The Odette FTP adapter has the following restrictions:
|
Persistence level | The adapter has no pre-set persistence level. |
Testing considerations | For testing ISDN, you need a system handling the OFTP Partner role. For CAPI/ISDN communication, a BINTEC ISDN Router is required. In a loop back scenario, Sterling B2B Integrator can be configured to take over the role of both an OFTP Initiator and an OFTP Responder. |
Prerequisite
You must be familiar with the Odette File Transfer Protocol and ISDN or TCP/IP protocol.
Sample Business Scenario
You have many files to send each day. You can send them in one transmission (OFTP session) to your partner by putting all files into the partner's Queue (Queue Handler Mode) or by passing more than one DataItem (document) in the OFTPDataSet XML structure (manual mode and Mailbox mode). This is much more efficient than initiating an OFTP session for each single file.
If the Odette FTP adapter is invoked, the business process remains in WAIT_ON_IO status until communication has ended. This includes sending and receiving files and acknowledgements (EERP/NERP). Then, the adapter reactivates the process and writes an OFTPResponse XML structure into the process data.
File Transmission Retries
- When a file is scheduled to transfer, the status filed in OFTP_OBJECT says SCHEDULED.
- While the file is being transferred the status in the OFTP_OBJECT says RETRY. This means the file has not been sent successfully and a sent retry is performed. It is an intermediate status only.
- If the file is interrupted for some reason during transfer, the OFTP_OBJECT says RETRY_PENDING. This means the file transfer is interrupted and the same file can be retried later.
- Once the retry count is over and the file transfer is not been successful, status in OFTP_OBJECT table says FAIL This is the final error status for outbound direction if the retry counter is exceeded.
Implementing the Odette FTP Adapter in Queue Handler Mode
- If you want to use Mailbox Mode, create user accounts, virtual roots, and Mailboxes with Inboxes for you and all your partners.
- Activate your license for the Odette FTP adapter and for the Mailbox (if used).
- Create an Odette FTP adapter configuration.
- Configure the adapter.Note: Check the Odette FTP log file before using the adapter.
- Create a business process that passes the PhysicalPartnerContract parameter to the adapter.
- Test the business process and the adapter.
- Enable the OFTP Scheduler service if you have created a Time Schedule in the Sterling B2B Integrator Scheduler.
- Use the Odette FTP Queue Handler service to send messages.
Implementing the Odette FTP Adapter in Manual Mode
- Activate your license for the Odette FTP adapter.
- Create an Odette FTP adapter configuration.
- Configure the adapter.Note: Check the Odette FTP log file before using the adapter. Verify that the adapter has been started without errors. Otherwise, the adapter is not ready to use.
- Create and enable a business process that includes the Odette FTP adapter. You can use the sample business processes (oftpin and oftpout) and modify them to suit your installation.
- Create the OFTP Data Set XML structure in process data with the appropriate parameters so it can be passed to the adapter.
- Test the business process and the adapter.
Configuring the Odette FTP Adapter
To configure the Odette FTP adapter, specify field settings in Sterling B2B Integrator or the GPM:
Field | Description |
---|---|
Name | Unique and meaningful name for the adapter configuration, for reference purposes. Required. |
Description | Meaningful description for the adapter configuration. Required. |
Select a Group | Select one of the options:
|
Communication Mode | The mode of communication for this instance. Required.
Valid values are:
|
Inbound Business Process Name | The name of the business process initiated for received files. Required for manual mode only. The business process name in the adapter configuration can be overridden by the business process selected in the Logical Partner Contract. |
User | For manual mode, the Sterling B2B Integrator user ID
to use with the business process. Required for manual mode. Type the
user ID, or select a user ID from the list. Valid value is any valid Sterling B2B Integrator user ID. Note: This
parameter allows someone who does not have rights to a specific business
process to run it. If you select Admin as the
user ID, you will inherit Administrative rights (for this run of the
business process only), and enable the scheduled run.
|
For Communication Mode of ISDN
Field | Description |
---|---|
ISDN Router Address | The name or IP address of the ISDN router. Required. |
ISDN Router Port | The port for the ISDN router. The adapter uses this port to open up an IP-socket to the router. Required. |
Controller Number | Select the controller number of your ISDN router which should be used for incoming calls. Required. |
Keep Alive Interval (in seconds, 0 = unlimited) | Maximum length of time (in seconds) to wait for the response from a finished transmission. This is the time that a business process will stay in consume mode. Default is 2. Required. Valid values include any positive integer between 0 and 9999999999. Specify 0 for unlimited wait time. |
Number of Channels | The number of channels supported by the ISDN router. See your ISDN router manual to obtain the number of supported channels. Default is 2. Required. |
Accept Local MSN | Whether to accept incoming calls from a partner for the ISDN MSN specified only (fill in the phone number) or accept all MSN (parameter left blank). Optional. |
CAPI Socket Timeout | The number of seconds before the CAPI socket times out. Default is 2. Required. |
Accept inbound CAPI calls without ACL check | Specifies whether you want to accept inbound CAPI calls with or without check the settings in the Access Control List of the Partner Profile. Valid values are Yes (accept calls without ACL check) and No. Default is Yes. Required. |
Accept inbound CAPI calls without Calling Partner Address | Specifies whether you want to accept inbound CAPI calls with or without the “Calling Party Address” field populated. Valid values are Yes (accept calls without the Calling Party Address field populated) and No. Default is Yes. Required. |
For Communication Mode of Non-Secure IP
Field | Description |
---|---|
Perimeter Server | Name of the Perimeter Server or Perimeter Server group. Required. |
IP Server Listener Port | TCP/IP port number for incoming IP calls. Optional. Default is 3305. |
Accept inbound calls without ACL check | Whether to verify inbound calls with the access control list. Default is Yes. Required. |
For Communication Mode of Secure IP
Field | Description |
---|---|
Perimeter Server | Name of the Perimeter Server or Perimeter Server group. Required. |
IP Server Listener Port | TCP/IP port number for incoming IP calls. Optional. Default is 6619. |
Accept inbound calls without ACL check | Whether to verify inbound calls with the access control list. Default is Yes. Required. |
System Certificate | Private key and certificate for server authentication. Required if Secure IP option is selected. |
Cipher Strength | Strength of the algorithms used to encrypt data.
Valid values are:
|
CA Certificate | Select one or more CA Certificates. Certificate used to validate the certificate of an OFTP client. This is the public key. If no CA certificate is selected, no client certification is performed. Optional. |
Example Business Process for Queue Handler Mode
This example shows a business process that sends one message to a partner:
<!-- Adapter: Odette FTP
Description: Example template process for initiating an OFTP session for a
Physical Partner Contract
(Odette FTP Queue Handler Mode)
Prerequisites:
- Read the Odette FTP documentation
- For communication type "ISDN" setup your ISDN Router. For comunication type
"IP", the GIS Perimeter Service is used.
- Configure the OFTP Partner Profile (use OFTP Partner Profile User Interface
or edit the PartnerProfile XML file template <gis_root>/install/properties/
PartnerProfile.xml and use script PartnerManager.sh to import the Partner
Profile into the database).
- Configure and enable the Odette FTP Adapter instance "OFTPSendFile"
- Put files into the Odette FTP Message Queue using the Odette FTP Queue Handler
(use template bpml "oftpfile")
- Create time schedules for initiating OFTP sessions for with the GIS Scheduler.
Enable the GIS Scheduler and OFTP Scheduler Service.
Input : <PhysicalPartnerContract/>ppc_name</PhysicalPartnerContract/>, where
ppc_name is the name of the Physical Partner Contract used by the Odette
FTP Adapter to search all entries in the OFTP mMessage Queue for this PPC
with status "SCHEDULED".
-->
<process name="oftpinitsession">
<sequence name="oftp">
<!-- Start OFTP send process in Queue Handler Mode-->
<operation name="SendOFTP">
<participant name="OFTPSendFile"/>
<output message="Out">
<assign to="." from="*"></assign>
</output>
<input message="In">
<assign to="." from="*"></assign>
</input>
</operation>
</sequence>
</process>
Parameter Passed from Business Process to Adapter - Queue Handler Mode Only
Field | Description |
---|---|
PhysicalPartnerContract | Name of the Physical Partner Contract as defined in the Partner Profile. The contract is used to look up the remote partner mailbox. |
Error Messages
Advanced Status | Description |
---|---|
OFTP_INITIALIZATION_FAILED | An error occurred during initializing of required components. For example, the Service Framework providing logging services did not start successfully. |
OFTP_SEND_FAILED | The adapter was not able to send the messages passed in the OFTPDataSet structure successfully. Details are given in the Status Report. |
DATASET_NOT_COMPLETE | In Manual Mode, the OFTPDataSet structure passed to the adapter was parsed and did not contain all required fields (LogicalPartnerContract, PhysicalPartner Contract). |
OFTP_FAILURE | A general error occurred during processing that does not fit into the categories
listed above. The reason is noted in the status report. Note: If the adapter couldn't be started
successfully, such as a wrong configuration, then check the Odette FTP log for error details. The
Partner Profile configuration may have errors.
|
WRONG_WF_PARAM | In Queue Handler Mode only, either the PhysicalPartnerContract is not found or the MailboxUser is not defined in the contract. |
Business Process Configuration - Manual Mode Only
You are provided with sample business processes for manual mode (oftpout for initiating a session to a partner) that you can modify to use with the Odette FTP adapter. Details on how to modify these business processes are given in XML comments in the preconfigured business processes. The preconfigured business processes require the Odette FTP adapter instance OFTPSendFile to be configured and enabled. There are no parameters to be configured in the GPM.
OFTP Data Set XML Structure - Manual Mode Only
The Odette FTP adapter is able to send one or multiple Sterling B2B Integrator messages to one physical partner within a single adapter call. The OFTP Data Set XML structure has to be created in the process data and passed to the adapter, as in the following example:
<OFTPDataSet PhysicalPartnerContract="physical_partner_contract_name">
<DataItem_1>
<properties>
Required.
<LogicalPartnerContract>log_partner_contract_name</LogicalPartnerContract>
Optional. 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>
<RecordDelimiter>one_or_two_delimiters<RecordDelimiter>
</properties>
<document index="1">
<PrimaryDocument SCIObjectID="document_id_1"/>
</document>
</DataItem_1>
Optional.
<DataItem_n>
…
</DataItem_n>
</OFTPDataSet>
Defining XML Node Name Parameters - Manual Mode Only
To define the XML node name parameters, refer to the table below. This table describes the parameters that need to match the definitions in the OFTP partner profile. Verify 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 |
---|---|
OFTPDataSet@PhysicalPartnerContract | The unique name of the physical partner contract as defined in the Partner Profile. This is an 80-character string. Required. |
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:
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.
|
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. |
OFTPFileUserField | Used as defined by your bilateral agreement with your partner. Optional. |
RecordDelimiter |
For Format "F" there are specified special cases: |
Example of the OFTPResponse XML Structure - Manual Mode Only
For each OFTP Data Set request, a response structure is created in the process data, which contains the process results of the Odette FTP adapter call. The following example shows a sample response structure:
<OFTPResponse PhysicalPartnerContract="physical_contract_name">
<DataItem_1>
<Status>[Success|Failure|Skipped]</Status>
<Reason>The long description</Reason>
<ReasonCode>two_digit_reason_code</ReasonCode>
<Retry>[Yes|No]</Retry>
</DataItem_1>
Optional:
<DataItem_n>
…
</DataItem_n>
</OFTPResponse>
The following table describes the parameters of the response structure:
Parameter | Description |
---|---|
OFTPResponse@PhysicalPartnerContract | The unique name of the physical partner contract as defined in the Partner Profile XML file. This is an 80-character string. |
Status | The status of the response structure. This is a
string. Valid values are:
|
Reason | This is a long error description. This is a string. |
ReasonCode | The error reason code as defined by the OFTP specification. |
Retry | If an error occurs, the field specifies whether the virtual file should be resent. Valid values are Yes and No. |
OFTP Inbound XML Structure
For each single file received from a partner, a business process is initiated with the following file description in the process data:
<?xml version="1.0" encoding="UTF-8"?>
<ProcessData>
<PrimaryDocument SCIObjectID="unique_document_id"/>
<OFTPInbound>
<Type>FILE</Type>
<FileName>virtual_file_name</FileName>
<FileSize>1</FileSize>
<Originator>originator_name</Originator>
<Destination>destination_name</Destination>
<Time>time</Time>
<Date>date</Date>
<FileFormat>[U|T|V|F]</FileFormat>
</OFTPInbound>
</ProcessData>
For each OFTP EERP and NERP notification, a business process is initiated containing following OFTPInbound structure in process data:
EERP
<OFTPInbound>
<Type>EERP</Type>
<FileName>virtual_file_name</FileName>
<Originator>originator_name</Originator>
<Destination>destination_name</Destination>
<Time>time</Time>
<Date>date</Date>
</OFTPInbound>
NERP
<OFTPInbound>
<Type>NERP</Type>
<FileName>virtual_file_name</FileName>
<Originator>originator_name</Originator>
<Destination>destination_name</Destination>
<Creator>NERP_creator</Creator>
<Time>time</Time>
<Date>date</Date>
<Reason><Reason>
</OFTPInbound>
- Reason - Why the partner rejected the file on application level.
- Creator - Specifies the creator of the NERP, which may be different from the Destination.
The following table describes the parameters of the OFTP inbound XML structure:
Parameter | Description |
---|---|
FileName | This is the OFTP virtual file name as defined by
the bilateral agreement with your partner. Note: The virtual file name,
date, and time are used to uniquely define a file.
|
FileSize | The amount of space used at the originator to store the virtual file. The size includes user data only and is specified in K (1024) bytes. |
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.
|
Originator | Identifies the sender of the virtual file. This is the location that mapped the data for transmission. |
Destination | Identifies the final recipient of the transmission. This is the location that looks into the virtual file content. |
FileFormat | This field specifies the format of the virtual
file. Valid values are:
|
Example Business Process for Manual Mode
This example shows a business process that sends one message to a partner. This example assumes that the Sterling B2B Integrator document is located in the process data root under /doc1.
<process name="oftpsend">
<sequence name="oftp">
<operation name="CreateOFTPDataSetStructure">
<participant name="AssignService"/>
<output message="fromProcessData">
<assign to="OFTPDataSet/@PhysicalPartnerContract"
from="'Sterling_VW1'"></assign>
<assign to="OFTPDataSet/DataItem_1/document" from="doc1/node()">
</assign>
<assign to="OFTPDataSet/DataItem_1/document/@index" from="'1'"></assign>
<assign to="OFTPDataSet/DataItem_1/properties/LogicalPartnerContract"
from="'SterlingAndVW'"></assign>
<!-- Add optional parameters here, if used -->
<assign to="." from="*"/>
</output>
<input message="toProcessData">
<assign to="." from="*"/>
</input>
</operation>
<!-- Start OFTP send process -->
<operation name="SendOFTP">
<participant name="OFTPSendFile"/>
<output message="Out">
<assign to="." from="*"></assign> <!-- Pass OFTPDataSet-->
</output>
<input message="In">
<assign to="." from="*"></assign> <!-- Get OFTPResponse -->
</input>
</operation>
</sequence>
</process>