Introduction

The FTPS connector allows you to send and receive files over FTP on top of a TLS/SSL connection.

Read through this user guide to understand how to set up and configure a basic flow using the connector. Track feature additions, compatibility, limitations and API version updates with each release of the connector using the Connector Release Notes. Review the connector operations and functionality using the Technical Reference alongside the demo applications.

MuleSoft maintains this connector under the Premium Category support policy.

Prerequisites

This document assumes that you are familiar with Mule, Anypoint Connectors, and Anypoint Studio Essentials. To increase your familiarity with Studio, consider completing a Anypoint Studio Tutorial. This page requires some basic knowledge of Mule Concepts, Elements in a Mule Flow, and Global Elements.

Hardware and Software Requirements

For hardware and software requirements, please visit the Hardware and Software Requirements page.

Compatibility

The FTPS connector is compatible with:

Application/Service

Version

Mule Runtime

3.6.x and later

FTPS

This connector works with any FTP server with built-in TLS/SSL support.

Installing the Connector

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

Upgrading from an Older Version

If you’re currently using an older version of the connector, a small popup appears in the bottom right corner of Anypoint Studio with an "Updates Available" message.

  1. Click the popup and check for available updates. 

  2. Click the Connector version checkbox and click Next and follow the instructions provided by the user interface. 

  3. Restart Studio when prompted. 

  4. After restarting, when creating a flow and using the connector, if you have several versions of the connector installed, you may be asked which version you would like to use. Choose the version you would like to use.

Additionally, we recommend that you keep Studio up to date with its latest version.

Configuring the Connector Global Element

To use the FTPS connector in your Mule application, you must configure a global FTPS element that can be used by the FTPS connector (read more about Global Elements).

In order to set FTPS configuration you must first know your endpoint configuration needs. See the Hello World sample project below for configuration example.

Using the Connector

Use Cases

  • Read file(s) over FTPS, alternatively using a wildcard pattern.

  • Write file over FTPS

  • Transfer files using Active and Passive FTP modes

  • Transfer files using Explicit and Implicit SSL modes

Tips

  • Whenever possible, use passive mode. It’s easier to set up from the client perspective

  • Polling the server is possible from the FTPS connector itself; there’s no need to use a Poll component. This is useful when waiting for a given file to be published by others.

Increasing Performance

The FTPS Connector supports compression out-of-the-box. If your FTP server supports compression mode (a.k.a "mode c") the FTPS Connector will detect this feature and enter in compression mode for you.

See a full list of operations for any version of the connector here.

Connector Namespace and Schema

When designing your application in Studio, the act of dragging the connector from the palette onto the Anypoint Studio canvas should automatically populate the XML code with the connector namespace and schema location.

Namespace: http://www.mulesoft.org/schema/mule/ftps Schema Location: http://www.mulesoft.org/schema/mule/connector/current/mule-ftps.xsd

If you are manually coding the Mule application in Studio’s XML editor or other text editor, define the namespace and schema location in the header of your Configuration XML, inside the <mule> tag. 

  
1
2
3
4
5
6
7
8
9
10
11
12


  
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:connector="http://www.mulesoft.org/schema/mule/connector"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core
               http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/connector
               http://www.mulesoft.org/schema/mule/connector/current/mule-connector.xsd">

      <!-- put your global configuration elements and flows here -->

</mule>

Using the Connector in a Mavenized Mule App

If you are coding a Mavenized Mule application, this XML snippet must be included in your pom.xml file.


  
1
2
3
4
5


  
<dependency>
    <groupId>com.modus</groupId>
    <artifactId>mule-connector-ftps</artifactId>
    <version>RELEASE</version>
</dependency>

Inside the <version> tags, put the desired version number, the word RELEASE for the latest release, or SNAPSHOT for the latest available version. The available versions to date are:

  • 1.0.9

  • 1.0.8

Demo Mule Applications Using Connector

Find a demo under Samples in the Technical Reference

Example Use Cases

  • Receive a file over FTPS

  • Write a file on the server over FTPS

  • Receive one or more files over FTPS filtering by wildcard pattern

The following example explains the configuration options of the FTPS Connector for sending and receiving files.

This sample will receive a file over FTPS by its full name and save it’s contents locally.

Step 1

Create a new Mule Project using as run-time Mule Server 3.6.0 EE or higher:

New project

Step 2

Locate the FTPS Connector on the right hand-side palette:

Locate the FTPS Connector on the right hand-side palette

Step 3

Drag and drop a FTPS connector over to the canvas:

Drag and drop a FTPS connector over to the canvas

Step 4

Create a connector configuration for the FTPS element:

Create a connector configuration for the FTPS element

Step 5

Set the FTPS settings according to your scenario. In this sample, we have an FTPS server running on localhost.

FTPS settings

  1. B2B settings
    Activate this option if the Global configuration options are being set using a B2B Provider.

  2. Connection settings
    Set the host of your FTP server, this can be an IP address or a host name. Set the port the FTP server is listening to (control channel). Set whether you prefer active or passive connection modes. Fill in the blanks in the Advanced tab if you go for active. If you want to use explicit mode, select EXPLICIT in the Encryption mode field. The Streaming option is suitable for large files; instead of reading the contents to a byte array in memory; an input stream will be passed as payload to the next component in the flow.

  3. Security - FTP
    Your user and password on the FTP server.

Advanced settings can also be applied if needed. Read below for a brief description for each.

FTPS settings

  1. Security - Certificates (Optional)
    If set, the FTPS connector will validate your server’s identity with these certs. Only JKS format is supported at the moment. If you want to disable server certificate validation, you’ll be able to find that option in this section as well, although it’s not recommended.

  2. Active Mode settings
    These fields are going to be read in case ACTIVE was selected as Transfer Mode. The Reported IP Address is the external IP address to use if your application runs within a LAN and the FTP server is external to it.

  3. Pre-processing
    The Upload temp directory sets the location on the server side where the files are going to be uploaded before they reach they final destination.

  4. Concurrent downloads
    The number of worker threads to use when downloading multiple files (useful when reading files using a wildcard pattern or a directory).

Step 6

Now let’s setup the connector’s Read File operation to retrieve a file securely from the FTP Server. File contents will be passed over to the next component in the flow.

Read File operation

  1. Basic Settings
    Select the Read operation

  2. General Options
    Enter the path and filename of the file you aim to read from the server. In our case we’re transferring modus-test-read.txt which is located at the /demo directory of the FTP user we’ve set.

  3. Post-processing
    After a file has been read, the connector will attempt to delete it from the server unless Move to Directory is set to an existing location on the server. This field is optional.

  4. Polling
    The connector polls the server for the specified file. By default it checks for the file every second. Once it gets it it will continue to read the file and inject it into the flow.

  5. B2B options
    The specification ID for inbound transactions set on the B2B platform. This field is required if the Use B2B Provider was checked in the global configuration.

Step 7

Now it’s up to you to decide what to do with the contents you just read. What we’re going to do is to write the contents to a file. The FTPS connector can help us with that as it gives us 2 extra bits of information: the original file name and its size.

write the contents to a file

You should have your application ready to read a file securely from a FTP server you trust.

Step 8

Finally, run the example as a Mule application:

run the example as a Mule application

If the file exists on the remote FTP server the Connector should read it and locate it under the* /tmp* folder as setup in Step 7.

Example Use Case - Write a file on the server over FTPS

This sample will write a file over FTPS using the contents received in the payload.

Steps 1 - 5

Same as in the previous example.

Step 6

Drag and drop the a File component into the canvas. Set it up to read any given file from your filesystem.

Step 7

Drag and drop the FTPS connector icon over the canvas, right next to the File component of the previous step. This is how it should look like:

FTPS connector icon over the canvas

Step 8

Now let’s set up the FTPS write file operation.

Now let’s set up the FTPS write file operation

As you can see, we’re reusing the Global Configuration element from the previous example. Review Step 5 of the previous example for further details.

  1. General options
    As in the Read operation you can select which path to upload your file to. Under Filename you can enter any MEL expression you want; we’re setting a fixed name for simplicity.

  2. B2B options
    The specification ID for outbound transactions set on the B2B platform. This field is required if the Use B2B Provider was checked in the global configuration.

Step 9

Save your changes, run the application and you’re done. The application should have written your file to the server under the name specified in the configuration.

Example Use Case - Receive one or more files over FTPS filtering by wildcard pattern

This sample will receive one or more files over FTPS filtering by a wildcard pattern.

Step 1 — 5

Same as in the previous example.

Step 6

Now let us setup the connector’s Read operation to retrieve a set of files securely from the FTPS server, but this time use a wildcard in the filename.

Read operation

Enter the path of the parent directory you aim to read the files from on the server.

Enter the File pattern as well; bear in mind this is a wildcard pattern. In our case we’re transferring every file that starts with “modusbox-”.

Step 7

Let’s see an example of how to use the files we’ve just read. Drag and drop a File connector and set it up like this:

drag and drop a File connector

The above screenshot shows that the files are saved in our local /tmp directory. Take a look at the File Name/Pattern configuration value. The fileName inbound property is added by the FTPS connector along with the fileSize property. These values can come in handy for when you need to deal with multiple files.

Step 8

Save your changes and run the application. The application will read files from the server matching the filename pattern and save them locally under the same filename they had on the server.

Connector Performance

To define the pooling profile for the connector manually, access the Pooling Profile tab in the applicable global element for the connector.

For background information on pooling, see Tuning Performance.

Additionally, the FTPS connector read operation has the ability to tune the maximum number of threads used on dowloads and the polling frequency.

Resources