Odette FTP Adapter

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

Implementing the Odette FTP Adapter in Queue Handler Mode

Implementing the Odette FTP Adapter in Manual Mode

Configuring the Odette FTP Adapter

To configure the Odette FTP adapter, specify field settings in Sterling B2B Integrator or the GPM:

For Communication Mode of ISDN

For Communication Mode of Non-Secure IP

For Communication Mode of Secure IP

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

Error Messages

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.

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:

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>

The following table describes the parameters of the OFTP inbound XML structure:

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>