Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

SFTP Connector

The SFTP Connector implements a secure file transport channel so that your Mule application can exchange files with external resources. SFTP uses the SSH security protocol to transfer messages. You can implement the SFTP endpoint as an inbound endpoint with a one-way exchange pattern, or as an outbound endpoint configured for either a one-way or request-response exchange pattern. Mule uses the JCraft library for SFTP SSH. 

Note: Mule 3.7 and newer supports SFTP retries.

Installation

You can install a connector in Anypoint Studio using the instructions in Installing a Connector from Anypoint Exchange.

Configuration

SFTP endpoint configuration consists of two stages:

  1. Decide where you want to place the SFTP endpoint within your Mule flow, then drag it from the Palette to the appropriate place in the sequence of building blocks that make up your Mule flow.

    1. If you place the SFTP endpoint at the beginning of the flow, it acts as an inbound endpoint (a message source), triggering the flow whenever it receives a message. (You can also use the Composite Source scope to wrap the SFTP endpoint along with other, similar endpoints (such as File or UDP) so that your flow can receive files through multiple transport channels).

    2. If you place the SFTP building block in the middle or at the end of the flow, it serves as an outbound endpoint, passing information out of the flow to external resources.

SFTP Inbound Endpoints can only be set to a one-way exchange pattern. SFTP Outbound Endpoints can be set to either a one-way or request-response exchange pattern. . Configure the SFTP endpoint by providing values for the fields on the various tabs on the properties editor, which you open by clicking the SFTP icon on the Message Flow canvas.

General Tab

image

Field Description

Display Name

Defaults to the generic endpoint name, which in this case is SFTP. Change the display name, which must be alpha-numeric, to reflect the endpoint’s specific role, for example, File Retrieval Endpoint.

Exchange Pattern

If set to one-way, an SFTP inbound or outbound endpoint sends the incoming message to the next building block in the flow. If an SFTP outbound endpoint is set to request-response (the SFTP inbound endpoint cannot be set to request-response), that outbound endpoint waits for a response before sending the message. One-way is the default for both the inbound and outbound SFTP endpoints.

Connector Configuration

Use the dropdown list to select a previously configured connector configuration for this endpoint. If you have not created a connector configuration for this type of endpoint, you can do so from this window by clicking the green plus sign (+). Click the Edit icon EditIcon to modify a previously created global element.

Output Pattern

(Applies to outbound SFTP endpoint only.) Specify a pattern for naming files that get sent from the File endpoint to the connected file system. If this is not set, the File endpoint uses the same file-naming pattern used for incoming files.

Example:


              
           
1
#[header:inbound:originalFilename]

Host

Identify the outgoing (local) SFTP server, then supply user credentials for connecting to this server. Defaults to localhost. Enter the Fully Qualified Domain Name (FQDN) or IP address of the server on your host machine that connects to the external SFTP server.

Port

The port that connects to the local (host) server. (Normally, 22)

Path

Specify a path that facilitates connection to the local server so that you don’t have to provide a username and password.

User

The username for authentication on the host server.

Password

The password for authentication on the host server.

General Tab - Global Element Properties Screens

After you click the Connector Configuration’s green plus sign (+) or the edit symbol EditIcon, the Global Elements Properties screens appear with tabs for General, Advanced, Properties, Reconnection, File, and Notes. You can specify optional server property information or notes as needed. The rest of the screens are described in this section.

Global Element Properties - General Tab

sftp_gen_gen

Field Description

Name

Configuration name

Output Pattern

(Applies to outbound SFTP endpoint only.) Specify a pattern for naming files that get sent from the File endpoint to the connected file system. If not set, the File endpoint uses the same file-naming pattern used for incoming files.

Example:


               
            
1
#[header:inbound:originalFilename]

Identity File

File location for the PKI private key file.

Passphrase

Passphrase for the identity file (if needed).

Show password

Set to make the characters in the Passphrase field visible.

Global Element Properties - Advanced Tab

sftp_gen_adv

Field Description

Dispatched Pool Fatctory

Configures Bean properties.

Dynamic Notifications

Indicate if you want dynamic email notifications.

Validate Connections

Validate connections. Enabled by default.

Connection Pool Size

Creates a connection pool size for one or more active connections. Specify a negative number for no limit of pool size, or set to zero (0) to indicate not to use a connection pool.

Polling Frequency

Frequency in milliseconds to check the read directory. The read directory is specified by the endpoint of the listening component.

File Age

Minimum age in milliseconds for Mule to wait before consuming a file. This allows a file write to complete before processing.

Note: The Mule server and the SFTP server must have synchronized time for file age to work correctly.

Size Check Wait Time

Wait time in milliseconds between size checks to determine if a file is ready to be processed. This allows a file write to complete before processing. You can disable this feature by setting to a negative number or omitting a value. When enabled, Mule performs two size checks waiting the specified time between calls. If both checks return the same value, the file is ready to process.

Global Element Properties - Reconnection Tab

sftp_gen_reconn

Field Description

Do not use a Reconnection strategy

Disables a strategy in the event of an SFTP connection failure.

Standard Reconnection

Enables a reconnection strategy where Mule retries the connection the number of reconnection attempts and waits the number of milliseconds between attempts.

Frequency (ms)

The number of milliseconds that Mule should wait between attempting to re-establish an SFTP connection after a failure.

Reconnection Attempts

The number of attempts Mule should make to re-establish an SFTP connection after a connection failure.

Reconnect Forever

Click if you want Mule to continually attempt to reconnect an SFTP connection after it fails. Mule continues to wait Frequency milliseconds between attempts to reconnect.

Custom Reconnection

Lets you specify a file containing custom properties for how you want to define a connection policy. The file contains a class definition for the RetryPolicyTemplate interface.

Class

Path to a file containing a class definition for the RetryPolicyTemplate interface.

Properties

Properties to set for the RetryPolicyTemplate interface.

Global Element Properties - File Tab

sftp_gen_file

Field Description

Archive Directory

(Applies to inbound SFTP endpoint only.) The directory on the Mule server where the file is archived. Create this folder before starting Mule for application deployment. The user that Mule runs under must have permissions to read and write to the folder.

Archive Temporary Receiving Directory

(Applies to inbound SFTP endpoint only.) Specify a directory in which the archive file is temporarily held before being forwarded to the archive directory. This temporary directory must be configured if archiving is implemented.

Archive Temporary Sending Directory

(Applies to inbound SFTP endpoint only.) Specify a directory in which the archived file is stored before it is sent to the outbound SFTP endpoint. This should be a sub-directory of the archive directory and must be specified if archiving is implemented.

Duplicate Handling

(Applies to outbound SFTP endpoint only.) Defines the behavior in case of duplicates.

Temp Directory Inbound

The directory in the inbound SFTP endpoint folder where incoming files are received. Ensure that the mule user is configured to create a temp folder. This folder is used to restart a failing file transfer.

Temp Directory Outbound

The directory in the outbound SFTP endpoint folder where outgoing files are staged before sending. Ensure that the mule user is configured to create a temp folder.

Keep File On Error

Click to assign a unique time-and-date-based namestamp to the file when it is moved to one of the temporary directories.

Auto Delete

(Applies to inbound SFTP endpoint only.) . Click this box to delete the file after it has been read.

Use Temp File Timestamp Suffix

This field gives the files in the temp directory a guaranteed unique name using the local time when the file was moved to the temp directory.

File Parser

Set either file-custom-filename-parser or file:expression-filename-parser.

Advanced Tab

studio-sftp-adv

Field Description

Address

Enter the address for this endpoint, such as, http://localhost:22/file.

Response Timeout

Specify how long the endpoint must wait for a response (in ms).

Encoding

Choose from a drop-down list the character set used for message data. (i.e., UTF-8).

Disable Transport Transformer

Check this box if you do not want to use the endpoint default response transport.

MIME Type

Select from the dropdown list one of the formats this endpoint supports.

Connector Endpoint

Use the drop-down list to select a previously configured global endpoint template, if any exist. If you have not created a global element for this type of endpoint, you do so by clicking Add and completing the fields on the pane that appears. Click Edit to modify a previously created global element.

Polling Frequency

(Applies to inbound SFTP endpoint only.) Specify how often to check for incoming messages. Default value is 1000 ms.

File Age

(Applies to inbound SFTP endpoint only.) Sets a minimum period a file must wait before it is processed. This helps ensure that long files are received in their entirety before processing starts. However, Mule and the SFTP server must be on synchronized time for this feature to work properly.

Size Check Wait Time

(Applies to inbound SFTP endpoint only.) The period to wait (in ms) between size-checks that determine if a file is ready to be processed.

Identity File and Passphrase Information

Information for PKI authentication.

Enable default events tracking

Enable default business event tracking for this endpoint.

Transformers Tab

studio-sftp-trans

Field Description

Request Transformer References

Enter a list of synchronous transformers that will be applied to the request before it is sent to the transport.

Response Transformer References

Enter a list of synchronous transformers that will be applied to the response before it is returned from the transport.

File Tab

studio-sftp-file-out

Field Description

Duplicate Handling

(Applies to outbound SFTP endpoint only.)  Defines the behavior in case of duplicates.

Temp Directory

The directory in the inbound SFTP endpoint folder where incoming files are received, or, in the case of an outbound SFTP endpoint, where outgoing files are staged before sending.

Keep File On Error

(Applies to outbound SFTP endpoint only.) If true, the file on the inbound endpoint will not be deleted if an error occurs while writing to the outbound endpoint.

Auto Delete

(Applies to inbound SFTP endpoint only.) Check this box to delete the file after it has been read.

See Also

See the SFTP Transport Reference for details on setting the properties for an SFTP endpoint using an XML editor.