FTPS Connector - Mule 3

Support Category: Premium

Anypoint Connector for FTPS (FTPS Connector) enables you to send and receive files over FTPS, providing seamless integration between Mule apps and an FTPS server.

Use this guide to set up and configure a basic Mule flow with the FTPS connector.

Release Notes: FTPS Connector Release Notes
Exchange: FTPS Connector

Prerequisites

This document assumes that you are familiar with FTPS, Mule, Anypoint connectors, Anypoint Studio, elements in a Mule flow, and global elements.

Hardware and Software Requirements

Compatibility

Application or Service Version

Mule

3.7.0 and later

Install the Connector

  1. In Anypoint Studio, click the Exchange icon in the Studio taskbar.

  2. Sign in to Exchange with your Anypoint Platform credentials.

  3. From Anypoint Exchange, click Provided by MuleSoft.

  4. Search for the Mule 3 connector and click Install.

Configure the FTPS Connector Global Element

You can configure a global element for the FTPS connector for use by multiple instances of the FTPS connector in your application. However, not all connector instances use the same global element or configuration. For example, multiple connectors in a flow might use different global elements or configurations to connect to multiple instances.

You can provide connection and other details in the Global Element Properties window. These settings are saved in a global element and referenced by applicable connector instances:

Configuration

In this example, the placeholder values refer to values saved in a .properties file, which exists by default in the src/main/resources folder of your project. See Configuring Properties.

For ease of maintenance and reusability, you should use a .properties file for your FTPS connector properties, rather than hardcoding these values in the global element. When you use the .properties file, you can deploy the app to different environments, such as production, development, and QA, changing the credentials, if needed. See Deploying to Multiple Environments.

Global Element Properties for FTPS Connector

Field Description

Username

User name on the FTPS server.

If the server allows anonymous login, you can use anonymous as the username.

Password

Password for the username.

For anonymous login, this field can be empty.

Host

Host address of the FTPS server.

Port

Port where the FTPS service is running.

Keystore path

Path to the keystore to use for SSL.

Keystore password

Password for the keystore file.

Read timeout

Time (milliseconds) that the consumer waits for a response before it times out.

The default value is 0 (infinite).

Connection timeout

Time (milliseconds) that the consumer attempts to establish a connection before it times out.

The default value is 0 (infinite).

Disable Certificate Validation

Option to disable SSL certificate validation, which ignores certificates and uses the Trust all policy.

This option is not recommended.

Encryption mode

Mode to invoke client security: IMPLICIT or EXPLICIT.

Transfer mode

Mode to establish data connection: PASSIVE or ACTIVE.

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 will be 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 Will throw a NoSuchElementException

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

  • WHEN_EXHAUSTED_GROW Will create a new Mule instance and return it, essentially making maxActive meaningless. If a positive maxWait value is supplied, it will block for, at most, that many milliseconds, after which a NoSuchElementException is thrown. If maxThreadWait is a negative value, it is blocked 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 Will not load any components into the pool on startup

  • INITIALISE_ONE Will load one initial component into the pool on startup

  • INITIALISE_ALL Will load all components in the pool on startup

Reconnection

Defines how Mule runtime engine attempts to manage a connection failure.

Field Type Description Default Value Required

Standard Reconnection

The reconnection strategy to use.

Standard Reconnection

A reconnection strategy to configure how many times a reconnection should be attempted and how long to wait between attempts.

Field Type Description Default Value Required

Frequency

Number

How often in milliseconds to reconnect.

Reconnection Attempts

Number

How many reconnection attempts to make.

Run the reconnection in a separated thread

Boolean

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

false

Reconnect Forever

A reconnection strategy that retries an infinite number of times at the specified frequency.

Field Type Description Default Value Required

Frequency

Number

How often in milliseconds to reconnect.

Run the reconnection in a separated thread

Boolean

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

false

Using the FTPS Connector

The FTPS connector is based on the concept of the endpoint. You can configure the global element either:

  • Inbound endpoint to read files from an FTPS server

  • Outbound connector to upload a file to an FTPS server

Connector Namespace and Schema

In Anypoint Studio, when you drag the FTPS connector from the palette to the canvas, Studio automatically populates the Mule application XML code with the FTP connector namespace and schema location.

Namespace:

xmlns:ftps="http://www.mulesoft.org/schema/mule/ftps"

Schema Location:

http://www.mulesoft.org/schema/mule/ftps http://www.mulesoft.org/schema/mule/ftps/current/mule-ftps.xsd

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

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:ftps="http://www.mulesoft.org/schema/mule/ftps"
      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/ftps
	       http://www.mulesoft.org/schema/mule/ftps/current/mule-ftps.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, include this XML snippet in your pom.xml file:

<dependency>
  <groupId>com.mulesoft.connectors</groupId>
  <artifactId>mule-ftps-transport</artifactId>
  <version>3.1.0</version>
</dependency>

Enter the current version number in the <version> tag. The current version is 3.1.0.

FTPS Connector Example Use Cases

The example use cases are intended for Anypoint Studio users.

If you are configuring the application in XML, skip to the example Mule application XML code to see how the FTPS global element and the connector are configured in the XML in each use case:

Read Files from an FTPS Server and Log File Content - Studio

To use Anypoint Studio to read files from an FTPS server:

  1. In Studio, click File > New > Mule Project to create a new Mule Project.

  2. With your project open, search the Studio palette for the FTPS connector that you previously installed.

  3. Drag a new FTPS connector onto the canvas.

  4. Drag a Logger after the FTPS element to log incoming messages in the console.

    Read flow

  5. Double-click the flow header and rename it read-flow.

    Read flow configuration

  6. Double-click the FTPS connector element and configure its properties to the following:

    Field Value

    Display Name

    FTPS (Streaming)

    Consumer Configuration

    FTPS_Basic_config (default name of a configuration)

    You can set this value to the name of any other configuration that you previously configured.

    Operation

    Read

    Directory to move to

    Directory to move the files after they are read from the server.

    If empty, the files are deleted.

    File name

    Filename pattern for the files to read.

    Maximum concurrent reads

    Number of threads (connections) to use to read files.

    ASCII Data Type

    Whether the files to read are ASCII or BINARY.

    The default is BINARY.

    Streaming

    Whether to send an InputStream as the message payload (true) or as a byte array (false).

    The default is false.

    Pooling period

    Interval to query the server for files.

    Read operation

  7. Select the logger and set its fields to the following:

    Logger

  8. Select Run As > Mule Application to deploy the app from Studio to Mule runtime engine.

    When a new file matching your filename pattern appears, its content should appear in the console.

Read Files from an FTPS Server - XML

To read files from an FTPS server, run this example Mule application that uses the XML code generated by Studio with the FTPS connector as a consumer:

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking"
	xmlns:ftps="http://www.mulesoft.org/schema/mule/ftps"
	xmlns="http://www.mulesoft.org/schema/mule/core"
	xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
	xmlns:spring="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans
	http://www.springframework.org/schema/beans/spring-beans-current.xsd
	http://www.mulesoft.org/schema/mule/core
	http://www.mulesoft.org/schema/mule/core/current/mule.xsd
	http://www.mulesoft.org/schema/mule/ftps
	http://www.mulesoft.org/schema/mule/ftps/current/mule-ftps.xsd
	http://www.mulesoft.org/schema/mule/ee/tracking
	http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd">
    <ftps:config name="FTPS_Basic_Config" username="${username}" password="${password}"
    host="${host}" port="${port}" disableCertificateValidation="true" doc:name="FTPS: FTPS Basic Config"/>
    <flow name="read-flow">
        <ftps:read config-ref="FTPS_Basic_Config" fileName="test_read*" filesPath="/files"
	pollingPeriod="10000" doc:name="FTPS (Streaming)" isASCII="true"/>
        <logger message="#[payload]" level="INFO" doc:name="Logger"/>
    </flow>
</mule>

Write Files to an FTPS Server - Studio

To write files to an FTP server:

  1. In Studio, click File > New > Mule Project to create a new Mule project..

  2. Navigate through the project structure and double-click src/main/app/project-name.xml.

  3. Drag a new HTTP element onto the canvas.

    This element is the entry point for the flow and provides data write to a file.

  4. Drag a new FTPS element after the HTTP Listener.

    Write flow

  5. Double-click the flow header (blue line) and change the name of the flow to write-flow.

    Write flow configuration

  6. Select the HTTP element.

  7. Click the plus sign next to the Connector Configuration dropdown.

  8. At the prompt, accept the default configurations, and then click OK.

  9. Set Path to write.

  10. Select the FTPS connector and set its properties to the following:

    Display Name Write

    Consumer Configuration

    FTPS_Basic_config (default name of a configuration)

    You can set this value to the name of any other configuration that you previously configured.

    Operation

    Write

    File Name

    Name of the file to create on the FTPS server.

    File Path

    Path on the FTPS server to create the file.

    Input Reference

    Data to write to the specified file.

    ASCII Data Type

    Whether the files to write are ASCII or BINARY.

    The default is BINARY.

    Append Contents

    Whether to append the contents passed to the operation to an existing file (true).

    Streaming

    Whether to upload the contents of the file as a stream (true) or all at once (false).

    Write operation

  11. Start the application and invoke the HTTP endpoint that you created to create the file on the FTPS server.

Write Files to an FTPS Server - XML

To write files to an FTPS server, run this example Mule application that uses the XML code generated by Studio with the FTPS connector as a message publisher:

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:http="http://www.mulesoft.org/schema/mule/http"
	xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking"
	xmlns:ftps="http://www.mulesoft.org/schema/mule/ftps"
	xmlns="http://www.mulesoft.org/schema/mule/core"
	xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
	xmlns:spring="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans
	http://www.springframework.org/schema/beans/spring-beans-current.xsd
	http://www.mulesoft.org/schema/mule/core
	http://www.mulesoft.org/schema/mule/core/current/mule.xsd
	http://www.mulesoft.org/schema/mule/ftps
	http://www.mulesoft.org/schema/mule/ftps/current/mule-ftps.xsd
	http://www.mulesoft.org/schema/mule/ee/tracking
	http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd
	http://www.mulesoft.org/schema/mule/http
	http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd">
    <ftps:config name="FTPS_Basic_Config" username="${username}" password="${password}"
    host="${host}" port="${port}" disableCertificateValidation="true" doc:name="FTPS: FTPS Basic Config"/>
    <http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8081"
    doc:name="HTTP Listener Configuration"/>
    <flow name="write-flow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/>
        <ftps:write config-ref="FTPS_Basic_Config" fileName="test_read.txt"
	filePath="/files" input-ref="&quot;Test file content&quot;" doc:name="FTPS"/>
    </flow>
</mule>