Contact Free trial Login

SFTP Connector Reference

Allows manipulating files through the FTP and SFTP.

Configurations


Config

Default configuration

Parameters

Name Type Description Default Value Required

Name

String

The name for this configuration. Connectors reference the configuration with this name.

x 

Connection

The connection types that can be provided to this configuration.

x 

Default Write Encoding

String

 

Expiration Policy

Configures the minimum amount of time that a dynamic configuration instance can remain idle before the runtime considers it eligible for expiration. This does not mean that the platform will expire the instance at the exact moment that it becomes eligible. The runtime will actually purge the instances when it sees fit.

 

Connection Types

SFTP Connection

An FileSystemProvider which provides instances of SftpFileSystem from instances of SftpConnector

Parameters

Name Type Description Default Value Required

Working Directory

String

The directory to be considered as the root of every relative path used with this connector. If not provided, it will default to the remote server default.

 

Preferred Authentication Methods

Array of Enumeration, one of:

  • GSSAPI_WITH_MIC

  • PUBLIC_KEY

  • KEYBOARD_INTERACTIVE

  • PASSWORD

Set of authentication methods used by the SFTP client. Valid values are: SSAPI_WITH_MIC, PUBLIC_KEY, KEYBOARD_INTERACTIVE and PASSWORD.

 

Known Hosts File

String

If provided, the client will validate the server's key against the one in the referenced file. If the server key doesn't match the one in the file, the connection is aborted.

 

Sftp Proxy Config

If provided, a proxy is used for the connection.

 

Connection Timeout

Number

A scalar value representing the amount of time to wait before a connection attempt times out. This attribute works in tandem with #connectionTimeoutUnit. Defaults to 10

10

 

Connection Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

A TimeUnit which qualifies the #connectionTimeout attribute. Defaults to SECONDS

SECONDS

 

Response Timeout

Number

A scalar value representing the amount of time to wait before a request for data times out. This attribute works in tandem with #responseTimeoutUnit. Defaults to 10

10

 

Response Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

A TimeUnit which qualifies the #responseTimeoutUnit attribute. Defaults to SECONDS

SECONDS

 

Host

String

The FTP server host, such as www.mulesoft.com, localhost, or 192.168.0.1, etc

x 

Port

Number

The port number of the SFTP server to connect on

22

 

Username

String

Username for the FTP Server. Required if the server is authenticated.

 

Password

String

Password for the FTP Server. Required if the server is authenticated.

 

Passphrase

String

The passphrase (password) for the identityFile if required. Notice that this parameter is ignored if #identityFile is not provided

 

Identity File

String

An identityFile location for a PKI private key.

 

PRNG Algorithm

Enumeration, one of:

  • AUTOSELECT

  • NativePRNG

  • SHA1PRNG

  • NativePRNGBlocking

  • NativePRNGNonBlocking

The Pseudo Random Generator Algorithm to use

AUTOSELECT

 

Reconnection

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment will fail if the test doesn't pass after exhausting the associated reconnection strategy

 

Pooling Profile

Characteristics of the connection pool

 

Associated Operations

Associated Sources

Operations

Copy

<sftp:copy>

Copies the file at the sourcePath into the targetPath. If targetPath doesn’t exist, and neither does its parent, then an attempt is made to create depending on the value of the createParentFolder argument. If createParentFolder is false, then a SFTP:ILLEGAL_PATH error is thrown.

If the target file already exists, then it is overwritten if the overwrite argument is true. Otherwise, a SFTP:FILE_ALREADY_EXISTS error is thrown. As for the sourcePath, it can either be a file or a directory. If it points to a directory, then it is copied recursively.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x 

Source Path

String

The path to the file to be copied.

x 

Target Path

String

The target directory where the file is going to be copied.

x 

Create Parent Directories

Boolean

Whether or not to attempt creating any parent directories which don't exist.

true

 

Overwrite

Boolean

Whether or not to overwrite the file if the target destination already exists.

false

 

Rename To

String

Copied file's new name. If not provided, original file name is kept.

 

Reconnection Strategy

A retry strategy in case of connectivity errors.

 

For Configurations

Throws

  • SFTP:RETRY_EXHAUSTED  

  • SFTP:ILLEGAL_PATH  

  • SFTP:CONNECTIVITY  

  • SFTP:FILE_ALREADY_EXISTS  

Create Directory

<sftp:create-directory>

Creates a new directory on directoryPath.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x 

Directory Path

String

The new directory's name.

x 

Reconnection Strategy

A retry strategy in case of connectivity errors.

 

For Configurations

Throws

  • SFTP:RETRY_EXHAUSTED  

  • SFTP:ACCESS_DENIED  

  • SFTP:ILLEGAL_PATH  

  • SFTP:CONNECTIVITY  

  • SFTP:FILE_ALREADY_EXISTS  

Delete

<sftp:delete>

Deletes the file pointed by path, provided that it's not locked

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x 

Path

String

The path to the file to be deleted.

x 

Reconnection Strategy

A retry strategy in case of connectivity errors.

 

For Configurations

Throws

  • SFTP:RETRY_EXHAUSTED  

  • SFTP:ACCESS_DENIED  

  • SFTP:ILLEGAL_PATH  

  • SFTP:CONNECTIVITY  

List

<sftp:list>

Lists all the files in the directoryPath that match the given matcher. If the listing encounters a directory, the output list includes its contents depending on the value of the recursive parameter. If recursive is set to true but a found directory is rejected by the matcher, then there isn't any recursion into that directory.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x 

Directory Path

String

The path to the directory to be listed.

x 

Recursive

Boolean

Whether to include the contents of sub-directories. Defaults to false.

false

 

File Matching Rules

A matcher used to filter the output list.

 

Target Variable

String

The name of a variable on which the operation's output is placed.

 

Target Value

String

An expression that is evaluated against the operation's output. The outcome of that expression is stored in the target variable.

#[payload]

 

Reconnection Strategy

A retry strategy in case of connectivity errors.

 

Output

Type

Array of Message of [Binary] payload and [Sftp File Attributes] attributes

For Configurations

Throws

  • SFTP:RETRY_EXHAUSTED  

  • SFTP:ACCESS_DENIED  

  • SFTP:ILLEGAL_PATH  

  • SFTP:CONNECTIVITY  

Move

<sftp:move>

Moves the file at the sourcePath into the targetPath. If targetPath doesn’t exist, and neither does its parent, then an attempt is made to create depending on the value of the createParentFolder argument. If createParentFolder is false, then a SFTP:ILLEGAL_PATH error is thrown. If the target file already exists, then it is overwritten if the overwrite argument is true. Otherwise, a SFTP:FILE_ALREADY_EXISTS error is thrown. As for the sourcePath, it can either be a file or a directory. If it points to a directory, then it is moved recursively.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x 

Source Path

String

The path to the file to be copied.

x 

Target Path

String

The target directory.

x 

Create Parent Directories

Boolean

Whether or not to attempt creating any parent directories which don't exist.

true

 

Overwrite

Boolean

Whether or not to overwrite the file if the target destination already exists.

false

 

Rename To

String

Moved file's new name. If not provided, original file name is kept.

 

Reconnection Strategy

A retry strategy in case of connectivity errors.

 

For Configurations

Throws

  • SFTP:RETRY_EXHAUSTED  

  • SFTP:ILLEGAL_PATH  

  • SFTP:CONNECTIVITY  

  • SFTP:FILE_ALREADY_EXISTS  

Read

<sftp:read>

Obtains the content and metadata of a file at a given path. The operation itself returns a Message whose payload is an InputStream with the file’s content, and the metadata is represented as a SftpFileAttributes object that’s placed as the message Message#getAttributes() attributes.

If the lock parameter is set to true, then a file system level lock is placed on the file until the input stream this operation returns is closed or fully consumed. Because the lock is actually provided by the host file system, its behavior might change depending on the mounted drive and the operating system on which Mule is running. Take that into consideration before blindly relying on this lock.

This method also makes a best effort to determine the MIME type of the file being read. The file’s extension is used to make an educated guess on the file’s MIME type. The user also has the chance to force the output encoding and mimeType through the outputEncoding and outputMimeType optional parameters.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x 

File Path

String

The path to the file to be read.

x 

Lock

Boolean

Whether or not to lock the file. Defaults to false.

false

 

Output Mime Type

String

The MIME type of the payload that this operation outputs.

 

Output Encoding

String

The encoding of the payload that this operation outputs.

 

Streaming Strategy

Configure if repeatable streams should be used and their behavior.

 

Target Variable

String

The name of a variable on which the operation's output is placed.

 

Target Value

String

An expression that is evaluated against the operation's output. The outcome of that expression is stored in the target variable.

#[payload]

 

Reconnection Strategy

A retry strategy in case of connectivity errors.

 

Output

Type

Binary

Attributes Type

For Configurations

Throws

  • SFTP:RETRY_EXHAUSTED  

  • SFTP:ACCESS_DENIED  

  • SFTP:FILE_LOCK  

  • SFTP:ILLEGAL_PATH  

  • SFTP:CONNECTIVITY  

Rename

<sftp:rename>

Renames the file pointed by path to the name provided on the to parameter. The to argument should not contain any path separator. SFTP:ILLEGAL_PATH is thrown if this precondition is not honored.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x 

Path

String

The path to the file to be renamed.

x 

New Name

String

The file's new name.

x 

Overwrite

Boolean

Whether or not to overwrite the file if the target destination already exists.

false

 

Reconnection Strategy

A retry strategy in case of connectivity errors.

 

For Configurations

Throws

  • SFTP:RETRY_EXHAUSTED  

  • SFTP:ACCESS_DENIED  

  • SFTP:ILLEGAL_PATH  

  • SFTP:CONNECTIVITY  

  • SFTP:FILE_ALREADY_EXISTS  

Write

<sftp:write>

Writes the content into the file pointed by path. If the directory on which the file is attempting to be written doesn’t exist, then the operation will either throw an SFTP:ILLEGAL_PATH error or create such folder depending on the value of createParentDirectory.

If the file itself already exists, then the behavior depends on the supplied mode. This operation also supports locking depending on the value of the lock argument, but following the same rules and considerations as described in the read operation.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x 

Path

String

The path of the file to be written.

x 

Content

Binary

The content to be written into the file. Defaults to the current Message payload.

#[payload]

 

Encoding

String

When content is a String, this attribute specifies the encoding to be used when writing. If not set, then it defaults to FileConnectorConfig#getDefaultWriteEncoding()

 

Create Parent Directories

Boolean

Whether or not to attempt creating any parent directories which don't exist.

true

 

Lock

Boolean

Whether or not to lock the file. Defaults to false.

false

 

Write Mode

Enumeration, one of:

  • OVERWRITE

  • APPEND

  • CREATE_NEW

A FileWriteMode. Defaults to OVERWRITE.

OVERWRITE

 

Reconnection Strategy

A retry strategy in case of connectivity errors.

 

For Configurations

Throws

  • SFTP:RETRY_EXHAUSTED  

  • SFTP:ILLEGAL_CONTENT  

  • SFTP:ACCESS_DENIED  

  • SFTP:ILLEGAL_PATH  

  • SFTP:CONNECTIVITY  

  • SFTP:FILE_ALREADY_EXISTS  

Sources

On New File

<sftp:listener>

Polls a directory looking for files that have been created on it. One message is generated for each file that is found. The key part of this functionality is how to determine that a file is actually new.

Possible polling strategies:

  • Set the autoDelete parameter to true: This deletes each processed file after it has been processed, causing all files obtained in the next poll to be necessarily new.

  • Set moveToDirectory parameter: This moves each processed file to a different directory after it has been processed, achieving the same effect as autoDelete but without losing the file.

  • Use the watermarkMode parameter: This only picks files that have been created/updated after the last poll was executed.

A matcher can also be used for additional filtering of files.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x 

Directory

String

The directory in which polled files are contained.

 

Recursive

Boolean

Whether or not to also include files contained in sub directories.

true

 

Matcher

A matcher used to filter events on files which do not meet the matcher's criteria.

 

Watermark Enabled

Boolean

Controls whether or not to do watermarking, and if so, if the watermark should consider the file's modification or creation timestamps.

false

 

Output Mime Type

String

The MIME type of the payload that this operation outputs.

 

Output Encoding

String

The encoding of the payload that this operation outputs.

 

Primary Node Only

Boolean

Whether this source should only be executed on the primary node when running in Cluster.

 

Scheduling Strategy

Configures the scheduler that triggers the polling.

x 

Streaming Strategy

Configure if repeatable streams should be used and their behavior.

 

Redelivery Policy

Defines a policy for processing the redelivery of the same message.

 

Reconnection Strategy

A retry strategy in case of connectivity errors.

 

Auto Delete

Boolean

false

 

Move To Directory

String

 

Rename To

String

 

Apply Post Action When Failed

Boolean

true

 

Output

Type

Binary

Attributes Type

For Configurations

Types

SFTP Proxy Config

Field Type Description Default Value Required

Host

String

x

Port

Number

x

Username

String

Password

String

Protocol

Enumeration, one of:

  • HTTP

  • SOCKS4

  • SOCKS5

x

Reconnection

Field Type Description Default Value Required

Fails Deployment

Boolean

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment will fail if the test doesn’t pass after exhausting the associated reconnection strategy.

Reconnection Strategy

The reconnection strategy to use.

Reconnect

Field Type Description Default Value Required

Frequency

Number

How often in milliseconds to reconnect.

Count

Number

How many reconnection attempts to make.

blocking

Boolean

If false, the reconnection strategy runs in a separate, non-blocking thread.

true

Reconnect Forever

Field Type Description Default Value Required

Frequency

Number

How often in milliseconds to reconnect.

blocking

Boolean

If false, the reconnection strategy runs in a separate, non-blocking thread.

true

Pooling Profile

Field Type Description Default Value Required

Max Active

Number

Controls the maximum number of Mule components that can be borrowed from a session at one time. When set to a negative value, there is no limit to the number of components that may be active at one time. When maxActive is exceeded, the pool is said to be exhausted.

Max Idle

Number

Controls the maximum number of Mule components that can sit idle in the pool at any time. When set to a negative value, there is no limit to the number of Mule components that may be idle at one time.

Max Wait

Number

Specifies the number of milliseconds to wait for a pooled component to become available when the pool is exhausted and the exhaustedAction is set to WHEN_EXHAUSTED_WAIT.

Min Eviction Millis

Number

Determines the minimum amount of time an object may sit idle in the pool before it is eligible for eviction. When non-positive, no objects are evicted from the pool due to idle time alone.

Eviction Check Interval Millis

Number

Specifies the number of milliseconds between runs of the object evictor. When non-positive, no object evictor is executed.

Exhausted Action

Enumeration, one of:

  • WHEN_EXHAUSTED_GROW

  • WHEN_EXHAUSTED_WAIT

  • WHEN_EXHAUSTED_FAIL

Specifies the behavior of the Mule component pool when the pool is exhausted.

Possible values are:

  • WHEN_EXHAUSTED_FAIL - Throw a NoSuchElementException.

  • WHEN_EXHAUSTED_WAIT - Block by invoking Object.wait(long) until a new or idle object is available.

  • WHEN_EXHAUSTED_GROW - Create a new Mule instance and return it, essentially making maxActive meaningless.

If a positive maxWait value is supplied, it blocks for at most that many milliseconds, after which a NoSuchElementException is thrown. If maxThreadWait is a negative value, it blocks indefinitely.

Initialisation Policy

Enumeration, one of:

  • INITIALISE_NONE

  • INITIALISE_ONE

  • INITIALISE_ALL

Determines how components in a pool should be initialized.

The possible values are:

  • INITIALISE_NONE - Do not load any components into the pool on startup.

  • INITIALISE_ONE - Load an initial component into the pool on startup.

  • INITIALISE_ALL - Load all components into the pool on startup.

Disabled

Boolean

Whether pooling should be disabled.

Expiration Policy

Field Type Description Default Value Required

Max Idle Time

Number

A scalar time value for the maximum amount of time a dynamic configuration instance should be allowed to be idle before it’s considered eligible for expiration.

Time Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

A time unit that qualifies the maxIdleTime attribute.

Sftp File Attributes

Field Type Description Default Value Required

Directory

Boolean

Name

String

Path

String

Regular File

Boolean

Size

Number

Symbolic Link

Boolean

Timestamp

DateTime

Matcher

Field Type Description Default Value Required

Timestamp Since

DateTime

Timestamp Until

DateTime

Filename Pattern

String

Path Pattern

String

Directories

Enumeration, one of:

  • REQUIRE

  • INCLUDE

  • EXCLUDE

INCLUDE

Regular Files

Enumeration, one of:

  • REQUIRE

  • INCLUDE

  • EXCLUDE

INCLUDE

Sym Links

Enumeration, one of:

  • REQUIRE

  • INCLUDE

  • EXCLUDE

INCLUDE

Min Size

Number

Max Size

Number

Repeatable In Memory Stream

Field Type Description Default Value Required

Initial Buffer Size

Number

This is the amount of memory that is allocated in order to consume the stream and provide random access to it. If the stream contains more data than can be fit into this buffer, then it is expanded by according to the bufferSizeIncrement attribute, with an upper limit of maxInMemorySize.

Buffer Size Increment

Number

This is by how much buffer size is expanded if it exceeds its initial size. Setting a value of zero or lower will mean that the buffer should not expand, meaning that a STREAM_MAXIMUM_SIZE_EXCEEDED error is raised when the buffer gets full.

Max Buffer Size

Number

This is the maximum amount of memory that is used. If more than that is used then a STREAM_MAXIMUM_SIZE_EXCEEDED error is raised. A value lower or equal to zero means no limit.

Buffer Unit

Enumeration, one of:

  • BYTE

  • KB

  • MB

  • GB

The unit in which all these attributes are expressed

Repeatable File Store Stream

Field Type Description Default Value Required

Max In Memory Size

Number

Defines the maximum memory that the stream should use to keep data in memory. If more than that is consumed then it will start to buffer the content on disk.

Buffer Unit

Enumeration, one of:

  • BYTE

  • KB

  • MB

  • GB

The unit in which maxInMemorySize is expressed

Redelivery Policy

Field Type Description Default Value Required

Max Redelivery Count

Number

The maximum number of times a message can be redelivered and processed unsuccessfully before triggering process-failed-message.

Use Secure Hash

Boolean

Whether to use a secure hash algorithm to identify a redelivered message.

Message Digest Algorithm

String

The secure hashing algorithm to use. If not set, the default is SHA-256.

Id Expression

String

Defines one or more expressions to use to determine when a message has been redelivered. This property may only be set if useSecureHash is false.

Object Store

ObjectStore

The object store where the redelivery counter for each message is going to be stored.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub