Using the FTP Outbound Adapter

This chapter describes how to use the FTP outbound adapter (EnsLib.FTP.OutboundAdapter).

Tip:

InterSystems IRIS® also provides specialized business service classes that use this adapter, and one of those might be suitable for your needs. If so, no programming would be needed. See “Connectivity Options” in Introducing Interoperability Productions.

Overall Behavior

EnsLib.FTP.OutboundAdapter 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.OutboundAdapter, 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” in Developing Productions.

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

Your business operation class should extend Ens.BusinessOperation.
In your class, the ADAPTER parameter should equal EnsLib.FTP.OutboundAdapter.
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">
    <Method>methodname</Method>
  </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” in Developing Productions.
For information on defining the message handler methods, see “Creating Message Handler Methods,” later in this chapter.
For other options and general information, see “Defining a Business Operation Class” in Developing Productions.

Note:

Studio provides a wizard that you can use to create a business operation stub similar to the preceding. To access this wizard, click File —> New and then click the Production tab. Then click Business Operation and click OK.

Creating Message Handler Methods

When you create a business operation class for use with EnsLib.FTP.OutboundAdapter, 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:

Examine the inbound request message.
When you want to call one of the methods in EnsLib.FTP.OutboundAdapter, 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 the section “Calling Adapter Methods from the Business Operation. ”
Make sure that you set the output argument (pOutput). Typically you set this equal to the response message. This step is required.
Return an appropriate status. This step is required.

Calling Adapter Methods from the Business Operation

When your business operation class references the EnsLib.FTP.OutboundAdapter, the following adapter methods become available. You can call these adapter methods from the methods in your business operation class using the Adapter property as described in the previous topic:

Connect()

Method Connect(pTimeout As %Numeric = 30,
                pInbound As %Boolean = 0) As %Status

Connects to the FTP server and log in, setting the directory and transfer mode.

The FTP outbound adapter has a retry cycle, which it invokes to reestablish the connection when:

A TCP socket failure or timeout occurs while it is trying to establish a TCP connection to the FTP server
The local client responds with a network code (a timeout)
The local client responds with a retryable code (FTP codes 52x or 4xx, such as code 529 for a timeout)

CreateTimestamp()

ClassMethod CreateTimestamp(pFilename As %String = "",
                            pSpec As %String = "")
                            As %String

Using the pFilename string as a starting point, incorporates the time stamp specifier provided in pSpec and returns the resulting string. The default time stamp specifier is %f_%Q where:

%f is the name of the data source, in this case the input filename
_ is the literal underscore character, which will appear in the output filename
%Q indicates ODBC format date and time

In substituting a value for the format code %f, InterSystems IRIS strips out any of the characters |,?,\,/,:,[,],<,>,&,,,;,NUL,BEL,TAB,CR,LF, replacing spaces with underscores (_), slashes (/) with hyphens (-), and colons (:) with dots (.).

For full details about time stamp conventions, see “Time Stamp Specifications for Filenames” in Configuring Productions.

Delete()

Method Delete(pFilename As %String) As %Status

Deletes a named file from an FTP server. Server, Username, Password, and File Path are already configured as settings for this adapter. Returns a status value indicating the success of the FTP operation.

Disconnect()

Method Disconnect(pInbound As %Boolean = 0) As %Status

Disconnects from the FTP server.

GetStream()

Method GetStream(pFilename As %String,
                ByRef pStream As %Stream.Object = $$$NULLOREF) As %Status

Retrieves a named file from an FTP server and returns it as a stream. Server, Username, Password, FilePath and Transfer mode (Charset) are already configured as settings for this adapter. This method returns a status value indicating the success of the FTP operation. If the caller provides a stream, it must be the appropriate type of stream for the transfer (character or binary). This method will create the stream if none is provided.

NameList()

Method NameList(Output pFileList As %ListOfDataTypes) As %Status

Gets a list of files on an FTP server. Server, Username, Password, and FilePath are already configured as settings for this adapter. The filenames are returned in a %ListOfDataTypes object. This method returns a status value indicating the success of the FTP operation.

PutStream()

Method PutStream(pFilename As %String,
                pStream As %Stream.Object) As %Status

Stores a stream to an FTP server as a named file. Server, Username, Password, FilePath and Transfer mode (Charset) are already configured as settings for this adapter. This method returns a status value indicating the success of the FTP operation.

Rename()

Method Rename(pFilename As %String,
                pNewFilename As %String,
                pNewPath As %String = "") As %Status

Renames a file on an FTP server. Server, Username, Password, and FilePath are already configured as settings for this adapter. This method returns a status value indicating the success of the FTP operation.

TestConnection()

Method TestConnection()

Correct the properties reflecting the connection state, in case the adapter thinks it is connected but has lost the socket.

The following methods are also available. Each method corresponds to an adapter setting that the user can adjust using the Management Portal. Each time the user applies changes of a setting, InterSystems IRIS executes the corresponding SettingSet method. These methods provide the opportunity to make adjustments following a change in any setting. For detailed descriptions of each setting, see “Reference for Settings.”

CharsetSet()

Method CharsetSet(cset As %String) As %Status

Charset is the character set of the input file.

ConnectedSet()

Method ConnectedSet(pValue As %Boolean) As %Status

Connected is an internal property that tracks the adapter’s connection to the FTP server.

CredentialsSet()

Method CredentialsSet(pInVal As %String) As %Status

Credentials is a production credentials entry that can authorize a connection to the FTP server. For information on creating production credentials, see Configuring Productions.

FilePathSet()

Method FilePathSet(path As %String) As %Status

FilePath is the directory on the FTP server in which to look for files.

FTPPortSet()

Method FTPPortSet(port As %String) As %Status

FTPPort is the TCP Port on the FTP Server to connect to.

FTPServerSet()

Method FTPServerSet(server As %String) As %Status

FTPServer is the FTP Server to connect to. This can be the IP address or server name, as long as the domain host controller can resolve the name.

SSLConfigSet()

Method SSLConfigSet(sslcfg As %String) As %Status

SSLConfig is the TLS configuration entry to use to authenticate this connection.

Example Business Operation Class

The following code example shows a business operation class that references the EnsLib.FTP.OutboundAdapter:

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:

Add an instance of your business operation class to the production.
Configure the business service. For information on the settings, see “Reference for Settings.”
Enable the business operation.
Run the production.

Reference for Settings

Using the FTP Inbound Adapter

Using the FTP Outbound Adapter

Copy link to this sectionOverall Behavior

Copy link to this sectionCreating a Business Operation to Use the Outbound Adapter

Copy link to this sectionCreating Message Handler Methods

Copy link to this sectionCalling Adapter Methods from the Business Operation

Copy link to this sectionExample Business Operation Class

Copy link to this sectionAdding and Configuring the Business Operation