Connector to manipulate Files on a FTP/SFTP server

Configurations

Config

Allows manipulating files through the FTP and SFTP

Parameters

Name Type Description Default Value Required

Name

String

The name of this configuration. With this name can be later referenced.

x 

Connection

The connection types that can be provided to this configuration.

x 

Default Write Encoding

String

 

Connection Types

FTP Connection

An AbstractFtpConnectionProvider which provides instances of ClassicFtpFileSystem from instances of FtpConnector

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.

 

Transfer Mode

Enumeration, one of:

  • BINARY

  • ASCII

The transfer mode to be used. Currently BINARY and ASCII are supported.

Defaults to BINARY

BINARY

 

Passive

Boolean

Whether to use passive mode. Set to false to switch to active mode.

Defaults to true.

true

 

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 FTP server to connect

21

 

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.

 

Reconnection Strategy

A retry strategy in case of connectivity errors

 

Disable Validation

Boolean

Disables connection validation

 

Pooling Profile

Characteristics of the connection pool

 
SFTP Connection

An AbstractFtpConnectionProvider which provides instances of SftpFileSystem from instances of FtpConnector

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

  • publickey

  • keyboard_interactive

  • password

Set of authentication methods used by the SFTP client. Valid values are: gssapi-with-mic, publickey, 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 will be aborted.

 

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.

 

Reconnection Strategy

A retry strategy in case of connectivity errors

 

Disable Validation

Boolean

Disables connection validation

 

Pooling Profile

Characteristics of the connection pool

 

Associated Operations

Operations

Copy

http://www.mulesoft.org/schema/mule/ftp:copy

Copies the file at the sourcePath into the targetPath.

To support pass-through scenarios, the sourcePath attribute is optional. If not provided, then the current Message#getAttributes() value will be tested to be an instance of FileAttributes, in which case FileAttributes#getPath() will be used. If that's not the case, then an IllegalArgumentException will be thrown.

If targetPath doesn't exists, and neither does its parent, then an attempt will be made to create depending on the value of the createParentFolder argument. If such argument is , then an IllegalArgumentException will be thrown.

If the target file already exists, then it will be overwritten if the overwrite argument is true. Otherwise, IllegalArgumentException will be thrown.

It is also possible to use the targetPath to specify that the copied file should also be renamed. For example, if sourcePath has the value a/b/test.txt and targetPath is assigned to a/c/test.json, then the file will indeed be copied to the a/c/ directory but renamed as test.json

As for the sourcePath, it can either be a file or a directory. If it points to a directory, then it will be 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

 

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 exists.

true

 

Overwrite

Boolean

whether or not overwrite the file if the target destination already exists.

false

 

For Configurations.

Throws

  • FTP:RETRY_EXHAUSTED  

  • FTP:CONNECTIVITY  

  • FTP:FILE_ALREADY_EXISTS  

  • FTP:ILLEGAL_PATH  

Create Directory

http://www.mulesoft.org/schema/mule/ftp: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 

For Configurations.

Throws

  • FTP:RETRY_EXHAUSTED  

  • FTP:CONNECTIVITY  

  • FTP:FILE_ALREADY_EXISTS  

  • FTP:ILLEGAL_PATH  

  • FTP:ACCESS_DENIED  

Delete

http://www.mulesoft.org/schema/mule/ftp:delete

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

To support pass-through scenarios, the path attribute is optional. If not provided, then the current Message#getAttributes() value will be tested to be an instance of FileAttributes, in which case FileAttributes#getPath() will be used. If that's not the case, then an IllegalArgumentException will be thrown.

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

 

For Configurations.

Throws

  • FTP:RETRY_EXHAUSTED  

  • FTP:CONNECTIVITY  

  • FTP:ILLEGAL_PATH  

  • FTP:ACCESS_DENIED  

List

http://www.mulesoft.org/schema/mule/ftp:list

Lists all the files in the directoryPath which match the given matcher.

If the listing encounters a directory, the output list will include 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 won't be any recursion into such 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

One of:

a matcher used to filter the output list

 

Target Variable

String

The name of a variable on which the operation's output will be placed

 

Output

Type

Array of Message of [Binary] payload and [[FtpFileAttributes]] attributes

For Configurations.

Throws

  • FTP:RETRY_EXHAUSTED  

  • FTP:CONNECTIVITY  

  • FTP:ILLEGAL_PATH  

  • FTP:ACCESS_DENIED  

Move

http://www.mulesoft.org/schema/mule/ftp:move

Moves the file at the sourcePath into the targetPath.

To support pass-through scenarios, the sourcePath attribute is optional. If not provided, then the current Message#getAttributes() value will be tested to be an instance of FileAttributes, in which case FileAttributes#getPath() will be used. If that's not the case, then an IllegalArgumentException will be thrown.

If targetPath doesn't exists, and neither does its parent, then an attempt will be made to create depending on the value of the createParentFolder argument. If such argument is false, then an IllegalArgumentException will be thrown.

If the target file already exists, then it will be overwritten if the overwrite argument is true. Otherwise, IllegalArgumentException will be thrown.

It is also possible to use the targetPath to specify that the moved file should also be renamed. For example, if sourcePath has the value a/b/test.txt and targetPath is assigned to a/c/test.json, then the file will indeed be copied to the a/c/ directory but renamed as test.json

As for the sourcePath, it can either be a file or a directory. If it points to a directory, then it will be 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

 

Target Path

String

the target directory

x 

Create Parent Directories

Boolean

whether or not to attempt creating any parent directories which don't exists.

true

 

Overwrite

Boolean

whether or not overwrite the file if the target destination already exists.

false

 

For Configurations.

Throws

  • FTP:RETRY_EXHAUSTED  

  • FTP:CONNECTIVITY  

  • FTP:FILE_ALREADY_EXISTS  

  • FTP:ILLEGAL_PATH  

Read

http://www.mulesoft.org/schema/mule/ftp:read

Obtains the content and metadata of a file at a given path. The operation itself returns a Message which payload is a InputStream with the file's content, and the metadata is represent as a FtpFileAttributes object that's placed as the message Message#getAttributes() attributes.

If the lock parameter is set to true, then a file system level lock will be 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 operation 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. A MimetypesFileTypeMap will be 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 behaviour

 

Target Variable

String

The name of a variable on which the operation's output will be placed

 

Output

Type

Binary

Attributes Type

For Configurations.

Throws

  • FTP:RETRY_EXHAUSTED  

  • FTP:CONNECTIVITY  

  • FTP:FILE_LOCK  

  • FTP:ILLEGAL_PATH  

  • FTP:ACCESS_DENIED  

Rename

http://www.mulesoft.org/schema/mule/ftp:rename

Renames the file pointed by path to the name provided on the to parameter

To support pass-through scenarios, the path attribute is optional. If not provided, then the current Message#getAttributes() value will be tested to be an instance of FileAttributes, in which case FileAttributes#getPath() will be used. If that's not the case, then an IllegalArgumentException will be thrown.

to argument should not contain any path separator. IllegalArgumentException will be 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

 

New Name

String

the file's new name

x 

Overwrite

Boolean

whether or not overwrite the file if the target destination already exists.

false

 

For Configurations.

Throws

  • FTP:RETRY_EXHAUSTED  

  • FTP:CONNECTIVITY  

  • FTP:FILE_ALREADY_EXISTS  

  • FTP:ILLEGAL_PATH  

  • FTP:ACCESS_DENIED  

Write

http://www.mulesoft.org/schema/mule/ftp: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 IllegalArgumentException or create such folder depending on the value of the createParentDirectory.

If the file itself already exists, then the behavior depends on the supplied mode.

This operation also supports locking support depending on the value of the lock argument, but following the same rules and considerations as described in the read operation. not set, then it defaults to FileConnectorConfig#getDefaultWriteEncoding()

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

 

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

 

Create Parent Directories

Boolean

whether or not to attempt creating any parent directories which don't exists.

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

 

For Configurations.

Throws

  • FTP:RETRY_EXHAUSTED  

  • FTP:CONNECTIVITY  

  • FTP:ILLEGAL_CONTENT  

  • FTP:FILE_ALREADY_EXISTS  

  • FTP:ILLEGAL_PATH  

  • FTP:ACCESS_DENIED  

Types

Reconnect

Field Type

Frequency

Number

Count

Number

Blocking

Boolean

Reconnect Forever

Field Type

Frequency

Number

Pooling Profile

Field Type

Max Active

Number

Max Idle

Number

Max Wait

Number

Min Eviction Millis

Number

Eviction Check Interval Millis

Number

Exhausted Action

Enumeration, one of:

  • WHEN_EXHAUSTED_GROW

  • WHEN_EXHAUSTED_WAIT

  • WHEN_EXHAUSTED_FAIL

Initialisation Policy

Enumeration, one of:

  • INITIALISE_NONE

  • INITIALISE_ONE

  • INITIALISE_ALL

Disabled

Boolean

Matcher

Field Type

Timestamp Since

DateTime

Timestamp Until

DateTime

Filename Pattern

String

Path Pattern

String

Directory

Boolean

Regular File

Boolean

Symbolic Link

Boolean

Min Size

Number

Max Size

Number