Using the FTP Outbound Adapter

Overall Behavior

EnsLib.FTP.OutboundAdapterOpens in a new tab enables a production to send files via the FTP protocol. To use this adapter, you create and configure a business operation that uses the adapter. The business operation receives a message from within the production, looks up the message type, and executes the appropriate method. This method usually executes methods of the associated adapter.

Creating a Business Operation to Use the Outbound Adapter

To create a business operation to use the EnsLib.FTP.OutboundAdapterOpens in a new tab, you create a new business operation class. Later, add it to your production and configure it.

You must also create appropriate message classes, if none yet exist. See Defining Messages.

The following list describes the basic requirements of the business operation class:

• Your business operation class should extend Ens.BusinessOperationOpens in a new tab.

• In your class, the ADAPTER parameter should equal EnsLib.FTP.OutboundAdapterOpens in a new tab.

• In your class, the INVOCATION parameter should specify the invocation style you want to use, which must be one of the following.

  • Queue means the message is created within one background job and placed on a queue, at which time the original job is released. Later, when the message is processed, a different background job is allocated for the task. This is the most common setting.

  • InProc means the message will be formulated, sent, and delivered in the same job in which it was created. The job will not be released to the sender’s pool until the message is delivered to the target. This is only suitable for special cases.

• Your class should define a message map that includes at least one entry. A message map is an XData block entry that has the following structure:

  XData MessageMap
  {
  <MapItems>
    <MapItem MessageType="messageclass">
      <methodname>methodname</methodname>
    </MapItem>
    ...
  </MapItems>
  }
  
  

  

• Your class should define all the methods named in the message map. These methods are known as message handlers. Each message handler should have the following signature:

  Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
  

  

  Here Sample is the name of the method, RequestClass is the name of a request message class, and ResponseClass is the name of a response message class. In general, the method code will refer to properties and methods of the Adapter property of your business operation.

  For information on defining message classes, see Defining Messages.

  For information on defining the message handler methods, see Creating Message Handler Methods.

• For other options and general information, see Defining a Business Operation Class.

Creating Message Handler Methods

When you create a business operation class for use with EnsLib.FTP.OutboundAdapterOpens in a new tab, typically your biggest task is writing message handlers for use with this adapter, that is, methods that receive production messages and then communicate via FTP.

Each message handler method should have the following signature:

Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status

Here Sample is the name of the method, RequestClass is the name of a request message class, and ResponseClass is the name of a response message class.

In general, the method should do the following:

1. Examine the inbound request message.

2. When you want to call one of the methods in EnsLib.FTP.OutboundAdapterOpens in a new tab, use the Adapter property to identify the adapter object. The following example calls the method PutStream() from a business operation method:

     Quit ..Adapter.PutStream(pFilename,..%TempStream)
   

   

   You can use similar syntax to call any of the methods described in Calling Adapter Methods from the Business Operation.

3. Make sure that you set the output argument (pOutput). Typically you set this equal to the response message. This step is required.

4. Return an appropriate status. This step is required.

Available Adapter Methods

When your business operation class references the EnsLib.FTP.OutboundAdapterOpens in a new tab, the following adapter methods become available.

• CreateFilename() generates a filename.

• Delete() deletes a file.

• GetStream() retrieves a file and returns it as a stream.

• Namelist() gets a list of files on the FTP server.

• PutStream() writes a file to the FTP server (given a stream as input).

• Rename() renames a file.

You can call these adapter methods from the methods in your business operation class using the Adapter property as described previously.

Example Business Operation Class

The following code example shows a business operation class that references the EnsLib.FTP.OutboundAdapterOpens in a new tab:

Class EnsLib.FTP.PassthroughOperation Extends Ens.BusinessOperation
{
Parameter ADAPTER = "EnsLib.FTP.OutboundAdapter";

/// Name of file to output the document(s) to. May include timestamp
/// specifiers. The %f specifier if present will be replaced with the
/// name of the document's original source filename (stripped of 
/// characters illegal in filenames).  See the method 
/// Ens.Util.File.CreateTimestamp() for documentation of timestamping options.

Property Filename As %String(MAXLEN = 1000);

Parameter SETTINGS As %String = "Filename";

Method OnMessage(pRequest As Ens.StreamContainer,
                 Output pResponse As %Persistent) As %Status
  {
  Set tFilename=
  ..Adapter.CreateTimestamp(##class(%File).GetFilename(
    pRequest.Stream.Attributes("Filename")),..Filename)
  Quit ..Adapter.PutStream(tFilename, pRequest.Stream)
  }
}

Adding and Configuring the Business Operation

To add your business operation to a production, use the Management Portal to do the following:

1. Add an instance of your business operation class to the production.

2. Configure the business service. For information on the settings, see Settings for the FTP Outbound Adapter.

3. Enable the business operation.

4. Run the production.

See Also

• Settings for the FTP Outbound Adapter

• Using FTP

• Using SSH

• Using and debugging %Net.SSH.Session for SSH connectionsOpens in a new tab (article on the Developer Community)