Doc changes for sftp connector 2.3 release W-14911354

sftp/2.3/antora.yml

@@ -0,0 +1,15 @@
+name: sftp-connector
+version: '2.3'
+display_version: 2.3 (Mule 4)
+title: SFTP Connector
+nav:
+- modules/ROOT/nav.adoc
+asciidoc:
+  attributes:
+    page-component-desc: Provides access to files and folders on a SFTP server.
+    page-connector-type: Connector
+    page-connector-level: Select
+    page-exchange-group-id: org.mule.connectors
+    page-exchange-asset-id: mule-sftp-connector
+    page-runtime-version: 4.3.0
+    page-release-notes-page: release-notes::connector/connector-sftp.adoc

sftp/2.3/modules/ROOT/nav.adoc

@@ -0,0 +1,19 @@
+.xref:index.adoc[SFTP Connector]
+* xref:index.adoc[SFTP Connector Overview]
+* xref:sftp-documentation.adoc[SFTP Connector Reference]
+* xref:sftp-studio.adoc[SFTP Connector Studio Configuration]
+* xref:sftp-xml-maven.adoc[SFTP Connector XML and Maven Support]
+* xref:sftp-examples.adoc[SFTP Connector Examples]
+** xref:sftp-read.adoc[Read a File]
+** xref:sftp-write.adoc[Write a File]
+** xref:sftp-list.adoc[List Files]
+** xref:sftp-copy-move.adoc[Copy and Move Files]
+** xref:sftp-create-directory.adoc[Create a Directory]
+** xref:sftp-on-new-file.adoc[Trigger a Flow for a New Created or Updated File]
+** xref:sftp-connection.adoc[Connect to an SFTP Server]
+** xref:sftp-connection-dynamically.adoc[Connect to SFTP Servers Dynamically]
+** xref:sftp-pooling.adoc[Disable SFTP Connection Pooling]
+** xref:sftp-preferred-authentication.adoc[Configure Preferred Authentication Methods]
+** xref:sftp-security-configuration-override.adoc[Configure Security Parameters of SSH Connection]
+* xref:sftp-connector-troubleshooting.adoc[Troubleshooting SFTP Connector]
+* xref:sftp-connector-upgrade-guide.adoc[Upgrading and Migrating SFTP Connector]

sftp/2.3/modules/ROOT/pages/index.adoc

@@ -0,0 +1,42 @@
+= SFTP Connector - Mule 4
+:page-aliases: connectors::sftp/sftp-connector.adoc
+
+
+
+Anypoint Connector for SFTP (SFTP Connector) provides access to files and folders on an SFTP server. SFTP connector operations manage file transfers over the SFTP (Secure File Transfer Protocol) protocol. The connector's main features include:
+
+* The ability to read files or list directory contents on demand
+* Support for common SFTP operations such as creating directories, copying, moving, renaming, and deleting files
+* Support for locking files
+* File matching functionality
+* A design that is consistent with that of File Connector and FTP Connector
++
+The same set of operations is available on these connectors, and they behave similarly.
+
+== Representation of File Attributes
+
+Mule 4 provides a message structure of a payload and attributes in which the data moves around, making that payload a file content. The attributes provide an object that contains metadata on the payload and information such as the file’s name, path, size, and timestamps. For FTP Connector and SFTP Connector, these attributes are known as  _file attributes_.
+
+The Mule message contains the concepts of encoding and MIME type. These describe the format in which a payload is represented. The file attributes describe a file’s encoding and MIME type.
+
+== Before You Begin
+
+To use this connector, you must be familiar with:
+
+* Anypoint Connectors
+* Mule runtime engine (Mule)
+* Elements and global elements in a Mule flow
+* Creating a Mule app using Anypoint Studio (Studio)
+
+Before creating an app, you must have access to Anypoint Platform and Anypoint Studio.
+
+
+== Next Step
+
+After you complete the prerequisites, you are ready to create your own app and configure the connector using xref:sftp-studio.adoc[Anypoint Studio].
+
+== See Also
+
+* xref:connectors::introduction/introduction-to-anypoint-connectors.adoc[Introduction to Anypoint Connectors]
+* xref:connectors::introduction/intro-use-exchange.adoc[Use Exchange to Discover Connectors, Templates, and Examples]
+* https://help.mulesoft.com[MuleSoft Help Center]

sftp/2.3/modules/ROOT/pages/sftp-connection-dynamically.adoc

@@ -0,0 +1,153 @@
+= Connect to SFTP Servers Dynamically Example - Mule 4
+
+Many integrations require connecting to different servers based on a specific condition, such as:
+
+* Connecting to different invoice storage servers depending on the branch that emits an invoice
+* Connecting to different servers depending on an integration subject, such as in a multi-tenant use case
+
+To accommodate these use cases, the Anypoint Connector for SFTP (SFTP Connector) global configuration element supports parameter expressions that evaluate these conditions and connect to the correct server.
+
+The following example shows how to configure SFTP Connector to connect dynamically to multiple servers:
+
+. An HTTP *Listener* source initiates the flow by reading random content posted via HTTP.
+. The File Connector *Read* operation loads a recipients CSV file that contains a random set of SFTP destinations, with columns such as `host`, `user`, and `port`.
+. A DataWeave transformation maps the content and splits the CSV file.
+. A *For Each* component and an SFTP *Write* operation write the contents into each of the SFTP destinations.
++
+On each *For Each* iteration, the expressions set in the SFTP global configuration element resolve to a different value and establish different connections to each of the servers.
+
+To test this example, create the Mule application, and run and test the application with curl commands:
+
+.Connect to SFTP Servers Dynamically flow
+image::sftp-connection-dynamically.png[Connect to SFTP Servers Dynamically]
+
+== Create the Mule Application
+
+To create the Mule flow:
+
+. In the *Mule Palette* view, select *HTTP > Listener*.
+. Drag *HTTP Listener* to the Studio canvas.
+. On the *HTTP Listener* configuration screen, optionally change the value of the *Display Name* field.
+. Set the *Path* field to `/multitenant`
+. Click the plus sign (*+*) next to the *Connector configuration* field to configure a global element that can be used by all instances of HTTP Listener in the app.
+. On the *General* tab, set the following fields:
++
+* *Host*: `All Interfaces [0.0.0.0] (default)`
+* *Port*: `8081`
++
+. Click *OK*.
+. Drag a *Set Variable* component to the right of the *HTTP Listener* source.
+. Set the *Name* field to `content` and the *Value* field to `#[payload]`.
+. Drag the File Connector *Read* operation to the right of the *Set Variable* component.
+. Set the *File Path* field to `recipients.csv`. +
+This reads a CSV file that contains a random set of SFTP destinations with columns such as `host`, `user`, and `port`.
+. Click the plus sign (*+*) next to the *Connector configuration* field to configure a global element that can be used by all instances of File Connector in the app.
+. Accept the default settings and click *OK*.
+. On the *MIME Type* tab of the *Read* operation, for the *MIME Type* field, select `application/csv`.
+
+=== Configure Additional Components and Operations
+
+Continue creating your Mule application by adding additional components and operations:
+
+. In Studio, drag a *Transform Message* component to the right of the *Read* operation.
+. In the *Output* section of the component, add the following DataWeave code to map the columns of the CSV file:
++
+.DataWeave script:
+[source,dataweave,linenums]
+----
+%dw 2.0
+output application/java
+---
+payload map using (row = $) {
+   host: row.Host,
+   user: row.User,
+   password: row.Password}
+----
++
+. Drag a *For Each* component to the right of the *Transform Message* component.
+. Drag an SFTP *Write* operation into the *For Each* component. +
+On each For Each iteration, the *Write* operation writes the contents into each of the SFTP destinations.
+. Click the plus sign (*+*) next to the *Connector configuration* field to configure a global element that can be used by all instances of SFTP Write operation in the app, and set the following fields:
++
+* *Host*: `#[payload.host]`
+* *Username*: `#[payload.username]`
+* *Password*: `#[payload.password]`
++
+[start=6]
+. Click *OK*.
+. On the configuration screen, set the *Path* field to `demo.txt`.
+. Set the *Content* field to `payload`.
+. Drag a *Set Payload* component to the right of the *For Each* component.
+. Set the *Value* field to `Multicast Ok`.
+
+== Run and Test your Mule Application
+
+After creating your Mule application, run and test it:
+
+. In Studio, save your Mule app.
+. Click the project name in *Package Explorer* and then click *Run* > *Run As* > *Mule Application*.
+. Open a browser and type `+http://0.0.0.0:8081/multitenant+`. +
+
+Note about Mule 4 behavior for Mule 3 users:
+
+* The information posted through the HTTP Listener source is written to each SFTP site multiple times.
++
+Because the listener makes use of the xref:mule-runtime::streaming-about.adoc[repeatable streams feature], you do not need to worry about consuming the stream multiple times.
+
+* The For Each component automatically goes through each line of the CSV file.
++
+In Mule 3, you first needed to transform the CSV file into a Java structure, but because Mule 4 is now Java agnostic, this works out-of-the-box.
+
+When reading or listing files, you might be interested in the file's metadata (for example, the file name, full path, size, timestamp). The connector uses the Mule message attributes to access this information.
+
+
+== XML for Connecting to SFTP Servers Dynamically
+
+Paste this code into your Studio XML editor to quickly load the flow for this example into your Mule app:
+
+[source,xml,linenums]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+
+<mule xmlns:sftp="http://www.mulesoft.org/schema/mule/sftp" xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
+	xmlns:file="http://www.mulesoft.org/schema/mule/file"
+	xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 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/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
+http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/current/mule-file.xsd
+http://www.mulesoft.org/schema/mule/ee/core http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd
+http://www.mulesoft.org/schema/mule/sftp http://www.mulesoft.org/schema/mule/sftp/current/mule-sftp.xsd">
+	<http:listener-config name="HTTP_Listener_config" >
+		<http:listener-connection host="0.0.0.0" port="8081" />
+	</http:listener-config>
+	<file:config name="File_Config" doc:name="File Config"  />
+	<sftp:config name="SFTP_Config" doc:name="SFTP Config"  >
+		<sftp:connection host="#[payload.host]" username="#[payload.user]" password="#[payload.password]" />
+	</sftp:config>
+	<flow name="SFTPexample" >
+		<http:listener doc:name="Listener" config-ref="HTTP_Listener_config" path="/multitenant"/>
+		<set-variable value="#[payload]" doc:name="Set Variable" variableName="content"/>
+		<file:read doc:name="Read" config-ref="File_Config" path="recipients.csv" outputMimeType="application/csv"/>
+		<ee:transform doc:name="Transform Message" >
+			<ee:message >
+				<ee:set-payload ><![CDATA[%dw 2.0
+output application/java
+---
+payload map using (row = $) {
+   host: row.Host,
+   user: row.User,
+   password: row.Password}]]></ee:set-payload>
+			</ee:message>
+		</ee:transform>
+		<foreach doc:name="For Each" >
+			<sftp:write doc:name="Write" config-ref="SFTP_Config" path="demo.txt">
+			</sftp:write>
+		</foreach>
+		<set-payload value="Multicast OK" doc:name="Set Payload" />
+	</flow>
+</mule>
+----
+
+== See Also
+
+* xref:sftp-examples.adoc[SFTP Connector Examples]
+* https://help.mulesoft.com[MuleSoft Help Center]

sftp/2.3/modules/ROOT/pages/sftp-connection.adoc

@@ -0,0 +1,124 @@
+= Connect to an SFTP Server Example - Mule 4
+
+The following examples show how to configure Anypoint Connector for SFTP (SFTP Connector) global configuration element to:
+
+* <<connect-sftp-server,Connect to an SFTP Server>>
+* <<connect-sftp-server-proxy,Connect to an SFTP Server Through a Proxy>>
+* <<configure-public-key,Configure a Public Key to connect to an SFTP server>>
+
+[[connect-sftp-server]]
+
+== Connect to an SFTP Server
+
+To configure the global element to connect to an SFTP Server, follow these steps:
+
+. Select the name of the connector in the Studio canvas.
+. Select the operation in the Studio canvas.
+. In the configuration screen for the operation, click the plus sign (*+*) next to the *Connector configuration* field to access the global element configuration fields.
+. On the *General* tab, specify the connection information for the connector.
+. If you want EdDSA support, provide the EdDSA dependency by clicking *Configure* under the *Required Libraries* field. +
+. Set the *Working Directory* field to `${workingDir}`. +
+This is root of every relative path used with this connector. If it's not provided, the value defaults to the remote server.
+. Set the *Host* field to specify the SFTP server host, for example `localhost` or `192.168.0.1`.
+. Set the *Port* field to `${sftpPort}`.
+. Set the *Username* field to `anonymous` and the *Password* field to `password`.
+. On the *Advanced* tab, optionally specify timeout configuration and reconnection strategy.
+. Click *Test Connection* to confirm that Mule can connect with the specified server.
+. Click *OK*.
+
+image::sftp-global-configuration-with-required-lib.png[SFTP Connector Global Element Configuration]
+
+In the Configuration XML editor, the configuration `sftp:config` looks like this:
+[source,xml,linenums]
+----
+<sftp:config name="sftp">
+  <sftp:connection username="anonymous" password="password"
+    host="localhost" port="${sftpPort}"
+    workingDir="${workingDir}"/>
+</sftp:config>
+----
+
+[[connect-sftp-server-proxy]]
+== Connect to an SFTP Server Through a Proxy
+
+To configure the global element to connect to an SFTP server through a proxy, follow these steps:
+
+. Select the name of the connector in the Studio canvas.
+. Select the operation in the Studio canvas.
+. In the configuration screen for the operation, click the plus sign (*+*) next to the *Connector configuration* field to access the global element configuration fields.
+. On the *General* tab, specify the connection information for the connector.
+. Set the *Working Directory* field to `${workingDir}`. +
+This is root of every relative path used with this connector. If it's not provided, the value defaults to the remote server.
+. Set the *Host* field to `127.0.0.100`.
+. Set the *Port* field to `${SFTP_PORT}`.
+. Set the *Username* field to `muletest1` and the *Password* field to `password`.
+. For the *Sftp proxy config* field, select *Edit inline*, and set the following fields:
++
+* *Host*: `localhost`
+* *Port*: `${proxyPort}`
+* *Protocol*: `HTTP` +
+The protocol can be either `HTTP` or `SOCKS5`.
++
+. On the *Advanced* tab, optionally specify a timeout configuration and reconnection strategy.
+. Click *Test Connection* to confirm that Mule can connect with the specified server.
+. Click *OK*.
+
+image::sftp-global-configuration-proxy.png[SFTP Connector Global Element Configuration]
+
+In the *Configuration XML* editor, the configuration `sftp:config` looks like this:
+
+[source,xml,linenums]
+----
+<sftp:config name="sftp">
+  <sftp:connection username="muletest1" password="password"
+    host="127.0.0.100" port="${SFTP_PORT}" workingDir="${workingDir}">
+      <sftp:sftp-proxy-config host="localhost" port="${proxyPort}" protocol="HTTP"/>
+  </ftp:sftp-connection>
+</ftp:config>
+----
+
+[[configure-public-key]]
+
+== Configure a Public Key to Connect to an SFTP Server
+
+The following example shows how to configure a public key as the preferred authentication method in your SFTP configuration. The example uses a PEM (Privacy Enhanced Mail) format certificate.
+
+. In Studio, navigate to the *Global Elements* tab.
+. Click *Create*.
+. Search for `sftp`.
+. Select *SFTP Config*.
+. Click *OK*.
+. In the Global Element Properties window, set *Preferred authentication methods* to *Edit inline*.
+. Click the plus sign to add a new value.
+. In the *Preferred authentication method* window, set *Value* to `PUBLIC_KEY`.
+. Click the plus sign to add a new value.
+. Set *Value* to `PASSWORD`.
+. Set *Host* to `sftp.host.com`.
+. Set *Port* to `22`.
+. Set *Username* to `sftp username`.
+. Set *Password* to `sftp password`.
+. Set *Identity file* to the PEM location folder, for example `Sftp-test-connection/src-main/resources/private.pem`.
+. Set *Passphrase* to the password of the identity file.
+. Click *OK*.
+
+image::sftp-global-configuration-key.png[SFTP Connector Global Element Configuration for public key]
+
+In the *Configuration XML* editor, the configuration looks like this:
+
+[source,xml,linenums]
+----
+<sftp:config name="SFTP_Config" doc:name="SFTP Config" >
+		<sftp:connection host="sftp.host.com" username="sftp username" password="sftp password" identityFile="Sftp-test-connection/src-main/resources/private.pem" passphrase="passwordfile" >
+			<sftp:preferred-authentication-methods >
+				<sftp:preferred-authentication-method value="PUBLIC_KEY" />
+				<sftp:preferred-authentication-method value="PASSWORD" />
+			</sftp:preferred-authentication-methods>
+		</sftp:connection>
+	</sftp:config>
+----
+
+
+== See Also
+
+* xref:sftp-examples.adoc[SFTP Connector Examples]
+* https://help.mulesoft.com[MuleSoft Help Center]