diff --git a/sftp/2.3/antora.yml b/sftp/2.3/antora.yml new file mode 100644 index 0000000000..46a0991955 --- /dev/null +++ b/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 diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-connection-dynamically.graffle/data.plist b/sftp/2.3/modules/ROOT/image-source-files/sftp-connection-dynamically.graffle/data.plist new file mode 100644 index 0000000000..05163bde83 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-connection-dynamically.graffle/data.plist differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-connection-dynamically.graffle/image1.png b/sftp/2.3/modules/ROOT/image-source-files/sftp-connection-dynamically.graffle/image1.png new file mode 100644 index 0000000000..98588a20ed Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-connection-dynamically.graffle/image1.png differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-copy-operation.graffle/data.plist b/sftp/2.3/modules/ROOT/image-source-files/sftp-copy-operation.graffle/data.plist new file mode 100644 index 0000000000..15c199c2f6 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-copy-operation.graffle/data.plist differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-copy-operation.graffle/image3.png b/sftp/2.3/modules/ROOT/image-source-files/sftp-copy-operation.graffle/image3.png new file mode 100644 index 0000000000..f458dbd93e Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-copy-operation.graffle/image3.png differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-create-directory-operation.graffle/data.plist b/sftp/2.3/modules/ROOT/image-source-files/sftp-create-directory-operation.graffle/data.plist new file mode 100644 index 0000000000..15c199c2f6 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-create-directory-operation.graffle/data.plist differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-create-directory-operation.graffle/image3.png b/sftp/2.3/modules/ROOT/image-source-files/sftp-create-directory-operation.graffle/image3.png new file mode 100644 index 0000000000..f458dbd93e Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-create-directory-operation.graffle/image3.png differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-global-configuration-key.graffle b/sftp/2.3/modules/ROOT/image-source-files/sftp-global-configuration-key.graffle new file mode 100644 index 0000000000..6c3984e55f Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-global-configuration-key.graffle differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-global-configuration-proxy.graffle/data.plist b/sftp/2.3/modules/ROOT/image-source-files/sftp-global-configuration-proxy.graffle/data.plist new file mode 100644 index 0000000000..edd563c31e Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-global-configuration-proxy.graffle/data.plist differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-global-configuration-proxy.graffle/image1.png b/sftp/2.3/modules/ROOT/image-source-files/sftp-global-configuration-proxy.graffle/image1.png new file mode 100644 index 0000000000..5e4d9fbad1 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-global-configuration-proxy.graffle/image1.png differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-global-configuration.graffle/data.plist b/sftp/2.3/modules/ROOT/image-source-files/sftp-global-configuration.graffle/data.plist new file mode 100644 index 0000000000..bf56c582a5 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-global-configuration.graffle/data.plist differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-global-configuration.graffle/image3.png b/sftp/2.3/modules/ROOT/image-source-files/sftp-global-configuration.graffle/image3.png new file mode 100644 index 0000000000..2cabafdc54 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-global-configuration.graffle/image3.png differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-1.graffle/data.plist b/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-1.graffle/data.plist new file mode 100644 index 0000000000..46c5e28490 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-1.graffle/data.plist differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-1.graffle/image3.png b/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-1.graffle/image3.png new file mode 100644 index 0000000000..5dbbb2bc76 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-1.graffle/image3.png differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-2.graffle/data.plist b/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-2.graffle/data.plist new file mode 100644 index 0000000000..4f16d577fb Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-2.graffle/data.plist differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-2.graffle/image4.png b/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-2.graffle/image4.png new file mode 100644 index 0000000000..3884937c8b Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-2.graffle/image4.png differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-3.graffle/data.plist b/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-3.graffle/data.plist new file mode 100644 index 0000000000..4f16d577fb Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-3.graffle/data.plist differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-3.graffle/image4.png b/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-3.graffle/image4.png new file mode 100644 index 0000000000..3884937c8b Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-3.graffle/image4.png differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-4.graffle b/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-4.graffle new file mode 100644 index 0000000000..c45f5f0080 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-list-operation-4.graffle differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-move-operation.graffle/data.plist b/sftp/2.3/modules/ROOT/image-source-files/sftp-move-operation.graffle/data.plist new file mode 100644 index 0000000000..eb729d67e3 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-move-operation.graffle/data.plist differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-move-operation.graffle/image2.png b/sftp/2.3/modules/ROOT/image-source-files/sftp-move-operation.graffle/image2.png new file mode 100644 index 0000000000..6766d094f4 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-move-operation.graffle/image2.png differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-newupdated-operation.graffle/data.plist b/sftp/2.3/modules/ROOT/image-source-files/sftp-newupdated-operation.graffle/data.plist new file mode 100644 index 0000000000..3ee6c1cc19 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-newupdated-operation.graffle/data.plist differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-newupdated-operation.graffle/image1.png b/sftp/2.3/modules/ROOT/image-source-files/sftp-newupdated-operation.graffle/image1.png new file mode 100644 index 0000000000..e2ff5603cc Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-newupdated-operation.graffle/image1.png differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-operations.graffle/data.plist b/sftp/2.3/modules/ROOT/image-source-files/sftp-operations.graffle/data.plist new file mode 100644 index 0000000000..bf56c582a5 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-operations.graffle/data.plist differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-operations.graffle/image3.png b/sftp/2.3/modules/ROOT/image-source-files/sftp-operations.graffle/image3.png new file mode 100644 index 0000000000..2cabafdc54 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-operations.graffle/image3.png differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-preferred-authentication.graffle b/sftp/2.3/modules/ROOT/image-source-files/sftp-preferred-authentication.graffle new file mode 100644 index 0000000000..61eaa90124 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-preferred-authentication.graffle differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-read-operation.graffle/data.plist b/sftp/2.3/modules/ROOT/image-source-files/sftp-read-operation.graffle/data.plist new file mode 100644 index 0000000000..91423f2ff7 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-read-operation.graffle/data.plist differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-read-operation.graffle/image1.png b/sftp/2.3/modules/ROOT/image-source-files/sftp-read-operation.graffle/image1.png new file mode 100644 index 0000000000..92bbb8a399 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-read-operation.graffle/image1.png differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-1.graffle/data.plist b/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-1.graffle/data.plist new file mode 100644 index 0000000000..648d6326d4 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-1.graffle/data.plist differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-1.graffle/image2.png b/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-1.graffle/image2.png new file mode 100644 index 0000000000..cb9a392808 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-1.graffle/image2.png differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-2.graffle/data.plist b/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-2.graffle/data.plist new file mode 100644 index 0000000000..d3896bcc29 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-2.graffle/data.plist differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-2.graffle/image3.png b/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-2.graffle/image3.png new file mode 100644 index 0000000000..a7b48fb498 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-2.graffle/image3.png differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-3.graffle/data.plist b/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-3.graffle/data.plist new file mode 100644 index 0000000000..8262b74a70 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-3.graffle/data.plist differ diff --git a/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-3.graffle/image3.png b/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-3.graffle/image3.png new file mode 100644 index 0000000000..a7b48fb498 Binary files /dev/null and b/sftp/2.3/modules/ROOT/image-source-files/sftp-write-operation-3.graffle/image3.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-connection-dynamically.png b/sftp/2.3/modules/ROOT/images/sftp-connection-dynamically.png new file mode 100644 index 0000000000..b921c2c4c3 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-connection-dynamically.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-copy-operation.png b/sftp/2.3/modules/ROOT/images/sftp-copy-operation.png new file mode 100644 index 0000000000..4f2f203731 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-copy-operation.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-create-directory-operation.png b/sftp/2.3/modules/ROOT/images/sftp-create-directory-operation.png new file mode 100644 index 0000000000..efca1ae123 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-create-directory-operation.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-global-configuration-key.png b/sftp/2.3/modules/ROOT/images/sftp-global-configuration-key.png new file mode 100644 index 0000000000..9bb3cd17b0 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-global-configuration-key.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-global-configuration-proxy.png b/sftp/2.3/modules/ROOT/images/sftp-global-configuration-proxy.png new file mode 100644 index 0000000000..67a7a191a0 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-global-configuration-proxy.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-global-configuration-with-required-lib.png b/sftp/2.3/modules/ROOT/images/sftp-global-configuration-with-required-lib.png new file mode 100644 index 0000000000..ed59a1b27f Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-global-configuration-with-required-lib.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-global-configuration.png b/sftp/2.3/modules/ROOT/images/sftp-global-configuration.png new file mode 100644 index 0000000000..7d5ef5ad0e Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-global-configuration.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-list-operation-1.png b/sftp/2.3/modules/ROOT/images/sftp-list-operation-1.png new file mode 100644 index 0000000000..4107302296 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-list-operation-1.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-list-operation-2.png b/sftp/2.3/modules/ROOT/images/sftp-list-operation-2.png new file mode 100644 index 0000000000..488acd0649 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-list-operation-2.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-list-operation-3.png b/sftp/2.3/modules/ROOT/images/sftp-list-operation-3.png new file mode 100644 index 0000000000..75363dbb06 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-list-operation-3.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-list-operation-4.png b/sftp/2.3/modules/ROOT/images/sftp-list-operation-4.png new file mode 100644 index 0000000000..ee5e73b3c0 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-list-operation-4.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-move-operation.png b/sftp/2.3/modules/ROOT/images/sftp-move-operation.png new file mode 100644 index 0000000000..6999642faa Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-move-operation.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-newupdated-operation.png b/sftp/2.3/modules/ROOT/images/sftp-newupdated-operation.png new file mode 100644 index 0000000000..210e5e01dc Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-newupdated-operation.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-operations.png b/sftp/2.3/modules/ROOT/images/sftp-operations.png new file mode 100644 index 0000000000..06df35c3e3 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-operations.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-override-config-file-contents.png b/sftp/2.3/modules/ROOT/images/sftp-override-config-file-contents.png new file mode 100644 index 0000000000..46f9791f04 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-override-config-file-contents.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-override-config-file-location.png b/sftp/2.3/modules/ROOT/images/sftp-override-config-file-location.png new file mode 100644 index 0000000000..dbaf674fe5 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-override-config-file-location.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-override-security-parameters.png b/sftp/2.3/modules/ROOT/images/sftp-override-security-parameters.png new file mode 100644 index 0000000000..5a2db35abb Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-override-security-parameters.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-pooling.png b/sftp/2.3/modules/ROOT/images/sftp-pooling.png new file mode 100644 index 0000000000..82354b24c1 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-pooling.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-preferred-authentication.png b/sftp/2.3/modules/ROOT/images/sftp-preferred-authentication.png new file mode 100644 index 0000000000..2ff1304706 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-preferred-authentication.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-read-operation.png b/sftp/2.3/modules/ROOT/images/sftp-read-operation.png new file mode 100644 index 0000000000..758b4a0fb4 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-read-operation.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-write-operation-1.png b/sftp/2.3/modules/ROOT/images/sftp-write-operation-1.png new file mode 100644 index 0000000000..9e249da45b Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-write-operation-1.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-write-operation-2.png b/sftp/2.3/modules/ROOT/images/sftp-write-operation-2.png new file mode 100644 index 0000000000..09419aca1b Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-write-operation-2.png differ diff --git a/sftp/2.3/modules/ROOT/images/sftp-write-operation-3.png b/sftp/2.3/modules/ROOT/images/sftp-write-operation-3.png new file mode 100644 index 0000000000..d05f354415 Binary files /dev/null and b/sftp/2.3/modules/ROOT/images/sftp-write-operation-3.png differ diff --git a/sftp/2.3/modules/ROOT/nav.adoc b/sftp/2.3/modules/ROOT/nav.adoc new file mode 100644 index 0000000000..96e7e76ef2 --- /dev/null +++ b/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] diff --git a/sftp/2.3/modules/ROOT/pages/index.adoc b/sftp/2.3/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000000..ccdb871433 --- /dev/null +++ b/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] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-connection-dynamically.adoc b/sftp/2.3/modules/ROOT/pages/sftp-connection-dynamically.adoc new file mode 100644 index 0000000000..f3bd9b23b7 --- /dev/null +++ b/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] +---- + + + + + + + + + + + + + + + + + + + + + + + + + + +---- + +== See Also + +* xref:sftp-examples.adoc[SFTP Connector Examples] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-connection.adoc b/sftp/2.3/modules/ROOT/pages/sftp-connection.adoc new file mode 100644 index 0000000000..99877589f0 --- /dev/null +++ b/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 + +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] +---- + + + +---- + +[[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] +---- + + + + + +---- + +[[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] +---- + + + + + + + + +---- + + +== See Also + +* xref:sftp-examples.adoc[SFTP Connector Examples] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-connector-troubleshooting.adoc b/sftp/2.3/modules/ROOT/pages/sftp-connector-troubleshooting.adoc new file mode 100644 index 0000000000..2fa05f6c8c --- /dev/null +++ b/sftp/2.3/modules/ROOT/pages/sftp-connector-troubleshooting.adoc @@ -0,0 +1,114 @@ += Troubleshooting SFTP Connector - Mule 4 + +To troubleshoot Anypoint Connector for SFTP (SFTP Connector), become familiar with the information about troubleshooting connectivity, permissions and server-side issues, troubleshooting Mule application issues, and interpreting commonly thrown messages. + +== Troubleshoot Connectivity, Permissions and Server-Side Issues + +Sometimes when attempting to connect to an SFTP server you can experience problems establishing the connection because an SFTP server requires a configured encrypted communication channel. +For example, you might need to enable specific encryption cyphers or key exchange algorithms, or indicate the location of certain authorization keys. + +To resolve this issue: + +. Locate the SFTP servers configuration file to review the parameters and settings regarding the connection, encryption methods, timeouts, and so forth. Correct configuration as necessary and customize the environment to suit your needs. +For example, if you are using OpenSSH you can access the `sshd_config` file. + +. Use the configuration file to increase the logging level on the server side. + +== Troubleshoot Mule Application Issues + +Sometimes you are not sure why the application is failing and you require a better understanding of what is going on in the app's interaction with the SFTP server. + +To resolve this error: + +* Use the configuration file to increase the logging level on the server side. + +* Try to replicate the issue using an SFTP client, for example, Cyberduck or Filezilla. If the issue also occurs with these clients, then it is likely that the issue is not related to the Mule app. + +* Get better and more detailed logs on the Mule app side by enabling verbose logging for SFTP Connector and for the library Apache Mina: ++ +. Access Anypoint Studio and navigate to the *Package Explorer* view. +. Open your application's project name. +. Open the `src/main/resources` path folder. +. Open the `log4j2.xml` file inside the folder. +. If the following line is already in the `log4j2.xml` file, uncomment it to enable it; otherwise, add it: ++ +[source,xml,linenums] +---- + + +---- +[start=6] +. Add the following argument to your run configuration: ++ + `-M-Djavax.net.debug=ssl,handshake` + +. To ensure the correlation ID is passed to child threads and visible in SSH logs, include the following argument in your run configuration: ++ + `-Dlog4j2.isThreadContextMapInheritable=true` + +* Try to minimize or remove unnecessary DataWeave data transformations (you could even use hard coded data) to minimize app's complexity and determine whether the issue is with the interaction between the app and the SFTP server. + +To get further information about enabling verbose logging for SDK components in your Mule application, see the xref:mule-sdk::troubleshooting.adoc[Troubleshooting SDK components] documentation. + + +[[common-throws]] +== Understand Common Throws + +Here is a list of common throws messages and how to interpret them. + +* SFTP:ILLEGAL_PATH + + The specified path is invalid because, for example, it does not exist. + +* SFTP:FILE_ALREADY_EXISTS + + An attempt was made to create a file at the same location and with the same name as an existing file. + This happens, for example, when attempting to write a file using the CREATE_NEW write mode to the path of an already existing file. + +* SFTP:ACCESS_DENIED + + An operation made an attempt to access an SFTP server path and perform an action for which the user has not been granted permission. + +* SFTP:FILE_LOCK + + An operation made an unsuccessful attempt to acquire a lock over a file. + +* SFTP:ILLEGAL_CONTENT + + The *Write* operation received invalid content to write. + +* SFTP:CONNECTIVITY + + The connection to the SFTP server was interrupted. + +* SFTP:INVALID_CREDENTIALS + + Authentication against the SFTP server failed due to invalid credentials. + +* SFTP:CONNECTION_TIMEOUT + + The attempt to connect to the SFTP server timed out. + +* SFTP:CANNOT_REACH + + An error occurred while attempting to establish the connection to the indicated SFTP server host and port. Typically, the connection is refused remotely, for example, if no process is listening on the remote address or port. + +* SFTP:UNKNOWN_HOST + + Mule cannot determine the IP address of a host. + +* SFTP:DISCONNECTED + + The app made too many failed login attempts to a server. This can result from multiple causes, but the most common one is invalid credentials. + +* SFTP:KEY_EXCHANGE_FAILED + + The app tried to make an SSH connection to the server, but failed in the key exchange step. Failure may occur during the negotiation or later steps in the key exchange. + +* FILE_DOESNT_EXIST + + The file to write was deleted. + +== See Also +* https://help.mulesoft.com[MuleSoft Help Center] +* xref:sftp-documentation.adoc[SFTP Connector Reference] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-connector-upgrade-guide.adoc b/sftp/2.3/modules/ROOT/pages/sftp-connector-upgrade-guide.adoc new file mode 100644 index 0000000000..32a1d74df5 --- /dev/null +++ b/sftp/2.3/modules/ROOT/pages/sftp-connector-upgrade-guide.adoc @@ -0,0 +1,201 @@ += Upgrade and Migrate SFTP Connector to Version 2.x - Mule 4 + +Upgrade Anypoint Connector for SFTP (SFTP Connector) to version 2.x.x. + +== Supported Upgrade Paths + +[%header,cols="50a,50a"] +|=== +|From Version | To Version +|1.6.0 |2.x.x +|=== + +== Changes in This Release + +This release contains the following changes: + +* The system property `mule.sftp.useHomeDirectory` was removed. SFTP Connector now uses the default home directory. +* SFTP Connector 2.x.x no longer supports the `jcraft library`. The connector now uses the `apache mina sshd` library. +* The *List* operation no longer fetches the content of each file. Now, the payload of each list item contains the complete path to the found file or directory. +* The SFTP *Regular Size* file attribute is renamed to *Regular File* because its behavior is not related to size. The file attribute value can be a file (`true`) or a directory (`false`). +* SFTP Connector 2.x.x does not support ciphers `3des-ctr` and `arcfour`. For more information, refer to <>. +* The SFTP proxy protocol works only with HTTP and SOCKS5. +* SFTP Connector no longer uses `javax.activation` to resolve the media types of the files. The connector now uses `Apache Tika`, which can result in different media file interpretations. +* The connector changed the classes to manage the date from `LocalDateTime` to `ZonedDateTime`. +* The deprecated *Encoding* parameter in the configuration and *Write* operation is removed. The connector uses the Mule's default encoding. +// List all changes that affect users, including changed schemas, +// changed data structures, changed POM files, changed and new fields +// (locations, names, etc) and parameters, deprecated parameters, etc + +// Examples: +// +// * The create operation name changed from old-name to new-name. +// * The field-name>is now located in the tab-name tab. +// * What happens with the upgrade? Are changes made to app data? +// * The single global configuration is divided into operation and source-specific global configurations like: +// ** send-config - used by send-with-sync-mdn and send-with-async-mdn operations. +// ** listener-config - used by as2-listener source. +// ** mdn-listener-config - used by as2-mdn-listener source. +// * Changed namespace from to . + +// If applicable, use tables to describe new and changed operations and sources. Examples follow: + +//// + +[[changed_operations]] +== Changed Operations + +[%header%autowidth.spread] +|=== +|Operation | Description | Parameters + +| , for example: *Commit* +a| Enter a description for the operation, for example: Commits the offsets associated to a message or batch of messages consumed in a message listener. a| Specify the operation parameters. Example: Consumer commit key. The consumer commit key to use to commit the message. +|=== + +[[changed_sources]] +== Changed Sources + +[%header%autowidth.spread] +|=== +|Source | Earlier version | Parameters + +| , for example: *Message listener* | ` configuration looks like this: +[source,xml,linenums] +---- + +---- + +== Configure the Move Operation in Studio + +To add and configure the *Move* operation in Studio, follow these steps: + +. In the *Mule Palette* view, search for `sftp` and select the *Move* operation. +. Drag the *Move* operation onto the Studio canvas. +. In the *General* tab of the operation configuration screen, click the plus sign (*+*) next to the *Connector configuration* field to access the global element configuration fields. +. Specify the connection information and click *OK*. +. Set the *Source path* field to the path of the file to move, for example, `source.txt`. +. In the *Target path* field, enter the directory path into which to move the file, for example `backup`. +. Set the *Rename to* field to rename the file as part of the operation, for example, `renamed.txt`. + +This field must be a filename, not a path. If this attribute is not provided, the original filename is used. + +image::sftp-move-operation.png[Move operation configuration in Studio] + +In the *Configuration XML* editor, the `` configuration looks like this: + +[source,xml,linenums] +---- + +---- + +== See Also + +* xref:sftp-examples.adoc[SFTP Connector Examples] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-create-directory.adoc b/sftp/2.3/modules/ROOT/pages/sftp-create-directory.adoc new file mode 100644 index 0000000000..34ffb49773 --- /dev/null +++ b/sftp/2.3/modules/ROOT/pages/sftp-create-directory.adoc @@ -0,0 +1,32 @@ += Create a Directory Using SFTP Connector Example - Mule 4 + +Anypoint Connector for SFTP (SFTP Connector) provides a *Create directory* operation that enables you to create a directory of a given name. + +If the reason for creating the directory is to immediately write, copy, or move content to the directory, then use the *Write*, *Copy*, or *Move* operations with the *Create parent directories* field set to *TRUE*. + +== Configure the Create Directory Operation in Studio + +To add and configure the *Create directory* operation in Studio, follow these steps: + +. In the *Mule Palette* view, search for `sftp` and select the *Create directory* operation. +. Drag the *Create directory* operation onto the Studio canvas. +. In the *General* tab of the operation configuration screen, click the plus sign (*+*) next to the *Connector configuration* field to access the global element configuration fields. +. Specify the connection information and click *OK*. +. Set the *Directory path* field to the new directory's path name, for example, `~/newFolder`. + +The following screenshot shows the *Create directory* operation configuration: + +.Create directory operation configuration +image::sftp-create-directory-operation.png[Create directory operation configuration in Studio] + +In the XML editor, the `` configuration looks like this: + +[source,xml,linenums] +---- + +---- + +== See Also + +* xref:sftp-examples.adoc[SFTP Connector Examples] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-documentation.adoc b/sftp/2.3/modules/ROOT/pages/sftp-documentation.adoc new file mode 100644 index 0000000000..7a70c08efb --- /dev/null +++ b/sftp/2.3/modules/ROOT/pages/sftp-documentation.adoc @@ -0,0 +1,751 @@ += SFTP Connector Reference - Mule 4 +:page-aliases: connectors::sftp/sftp-documentation.adoc + + + +SFTP Connector v2.1 + +Anypoint Connector for SFTP (SFTP Connector) provides access to files and folders on a SFTP server. + +Release Notes: xref:release-notes::connector/connector-sftp.adoc[SFTP Connector Release Notes] + +[NOTE] +PPK (Private Key) file does not support identity file for SFTP Connector. + +== Configurations +--- +[[config]] +=== Default Configuration + +==== Parameters +[%header,cols="20s,20a,35a,20a,5a"] +|=== +| Name | Type | Description | Default Value | Required +|Name | String | The name for this configuration. Connectors reference the configuration with this name. | | x +| Connection a| <> + | The connection types to provide to this configuration. | | x +| Time Between Size Check a| Number | Wait time between size checks to determine if a file is ready to read. This allows a file write to complete before processing. If no value is provided, the check will not be performed. When enabled, Mule waits the specified time between calls and performs two size checks. If both checks return the same value, the file is ready to read. This attribute works in tandem with *Time Between Size Check Unit*. | | +| Time Between Size Check Unit a| Enumeration, is one of: + +* NANOSECONDS +* MICROSECONDS +* MILLISECONDS +* SECONDS +* MINUTES +* HOURS +* DAYS | A TimeUnit that qualifies the *Time Between Size Check* attribute. + Defaults to `MILLISECONDS`. | `MILLISECONDS` | +| Expiration Policy a| <> | 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. Mule runtime engine purges the instances when it sees it fit. | | +|=== + +==== Connection Types + +[[config_connection]] +===== SFTP Connection + +A file system provider that provides instances of SFTP file system from instances of SFTP Connector. + +====== Parameters +[%header,cols="20s,20a,35a,20a,5a"] +|=== +| Name | Type | Description | Default Value | Required +| Working Directory a| String | The directory designated as the root of every relative path used with this connector. If not provided, it defaults to the remote server default. Define a working directory because some SFTP servers do not return output for the present working directory command. While the behavior of the SFTP server side cannot be controlled, setting this value mitigates such scenario. | | +| Preferred Authentication Methods a| Array of enumeration is one of: + +* GSSAPI_WITH_MIC +* PUBLIC_KEY +* KEYBOARD_INTERACTIVE +* PASSWORD | Set of authentication methods used by the SFTP client. Valid values are: `GSSAPI_WITH_MIC`, `PUBLIC_KEY`, `KEYBOARD_INTERACTIVE`, and `PASSWORD`. | | +| Known Hosts File a| String | If provided, the client validates 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. | | +| Sftp Proxy Config a| <> | If provided, a proxy will be used for the connection. | | +| Connection Timeout a| Number | A scalar value representing the amount of time to wait before a connection attempt times out. This attribute works in tandem with *Connection Timeout Unit*. + +Defaults to `10` | `10` | +| Connection Timeout Unit a| Enumeration is one of: + +* NANOSECONDS +* MICROSECONDS +* MILLISECONDS +* SECONDS +* MINUTES +* HOURS +* DAYS | A time unit that qualifies the *Connection Timeout* attribute. + Defaults to `SECONDS` | `SECONDS` | +| Response Timeout a| Number | A scalar value representing the amount of time to wait before a request for data times out. This attribute works in tandem with *Response Timeout Unit*. + Defaults to `10` | `10` | +| Response Timeout Unit a| Enumeration is one of: + +* NANOSECONDS +* MICROSECONDS +* MILLISECONDS +* SECONDS +* MINUTES +* HOURS +* DAYS | A TimeUnit that qualifies the *Response Timeout Unit* attribute. + Defaults to `SECONDS` | `SECONDS` | +| Host a| String | The SFTP server host, such as `www.mulesoft.com`, `localhost`, or `192.168.0.1`, and so on. | | x +| Port a| Number | The port number of the SFTP server to connect on. | `22` | +| Username a| String | Username for the SFTP Server. Required if the server is authenticated. | | +| Password a| String | Password for the SFTP Server. Required if the server is authenticated. | | +| Passphrase a| String | The passphrase (password) for the identity file if required. This parameter is ignored if identity file is not provided. | | +| Identity File a| String | An identity file location for a PKI private key. + +ssh-keygen's OpenSSH PKI format is not accepted. You can use argument "-m PEM". | | +| PRNG Algorithm a| Enumeration is one of: + +* AUTOSELECT +* NativePRNG +* SHA1PRNG +* NativePRNGBlocking +* NativePRNGNonBlocking | The Pseudo Random Number Generator Algorithm to use. | AUTOSELECT | +| Security Configuration a| <> | Provides support to override security related configurations like Ciphers, MACs, Kex Algorithms, etc. | | +| Reconnection a| <> | When the application is deployed, a connectivity test is performed on all connectors. If set to `true`, deployment fails if the test doesn't pass after exhausting the associated reconnection strategy. | | +| Pooling Profile a| <> | Characteristics of the connection pool. | | +|=== + +== Supported Operations + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +=== Associated Sources + +* <> + + +== Operations + +[[copy]] +=== Copy +`` + +Copies the file or directory specified in *Source Path* into the *Target Path*. The source path can be either a file or a directory. If it points to a directory, then it is copied recursively. + +If the target path doesn't exist, and neither does its parent, then a parent folder is created if *Create parent directories* is set to `true`. If *Create parent directories* is set to `false`, then an `SFTP:ILLEGAL_PATH` error is thrown. + +If *Overwrite* is set to `true` and the target file already exists, then the target file is overwritten. Otherwise, an `SFTP:FILE_ALREADY_EXISTS` error is thrown. + +==== Parameters +[%header,cols="20s,20a,35a,20a,5a"] +|=== +| Name | Type | Description | Default Value | Required +| Configuration | String | The name of the configuration to use. | | x +| Source Path a| String | The path to the file to copy. | | x +| Target Path a| String | The target directory for where to copy the file. | | x +| Create Parent Directories a| Boolean | Whether or not to attempt to create parent directories if they don't exist. | true | +| Overwrite a| Boolean | Whether or not to overwrite the file if the target destination already exists. | false | +| Rename To a| String | Rename the copied file. If this value is not provided, the original file name is kept. | | +| Reconnection Strategy a| * <> +* <> | A retry strategy in case of connectivity errors. | | +|=== + + +=== For Configurations +* <> + +==== Throws +* SFTP:RETRY_EXHAUSTED +* SFTP:ILLEGAL_PATH +* SFTP:FILE_ALREADY_EXISTS +* SFTP:CONNECTIVITY + + +[[createDirectory]] +=== Create Directory +`` + + +Creates a new directory using the value in the *Directory Path* field. + + +==== Parameters +[%header,cols="20s,20a,35a,20a,5a"] +|=== +| Name | Type | Description | Default Value | Required +| Configuration | String | The name of the configuration to use. | | x +| Directory Path a| String | The new directory's name. | | x +| Reconnection Strategy a| * <> +* <> | A retry strategy in case of connectivity errors. | | +|=== + + +=== For Configurations +* <> + +==== Throws + +* SFTP:RETRY_EXHAUSTED +* SFTP:ILLEGAL_PATH +* SFTP:ACCESS_DENIED +* SFTP:FILE_ALREADY_EXISTS +* SFTP:CONNECTIVITY + + +[[delete]] +=== Delete +`` + +Deletes the file that the path field points to, provided that the file is not locked. + + +==== Parameters +[%header,cols="20s,20a,35a,20a,5a"] +|=== +| Name | Type | Description | Default Value | Required +| Configuration | String | The name of the configuration to use. | | x +| Path a| String | The path to the file to delete. | | x +| Reconnection Strategy a| * <> +* <> | A retry strategy in case of connectivity errors. | | +|=== + + +=== For Configurations + +* <> + +==== Throws + +* SFTP:RETRY_EXHAUSTED +* SFTP:ILLEGAL_PATH +* SFTP:ACCESS_DENIED +* SFTP:CONNECTIVITY + + +[[list]] +=== List +`` + + +Lists all the files in the *Directory Path* depending on the rules in the File Matching Rules field. + +If the listing encounters a directory, the output list will include its contents, depending on the value of the *Recursive* field. + +If *Recursive* is set to the `true` value, but a found directory is rejected by the rules in the *File Matching Rules* field, then recursion does not occur in the directory. + + +==== Parameters +[%header,cols="20s,20a,35a,20a,5a"] +|=== +| Name | Type | Description | Default Value | Required +| Configuration | String | The name of the configuration to use. | | x +| Directory Path a| String | The directory path to list. | | x +| Recursive a| Boolean | Whether to include the contents of subdirectories. Defaults to `false`. | `false` | +| File Matching Rules a| <> | A matcher used to filter the output list. | | +| Time Between Size Check a| Number | Wait time between size checks to determine if a file is ready to read. | | +| Time Between Size Check Unit a| Enumeration is one of: + +* NANOSECONDS +* MICROSECONDS +* MILLISECONDS +* SECONDS +* MINUTES +* HOURS +* DAYS | Time unit to use in the wait time between size checks. | | +| Streaming Strategy a| * <> +* <> +* non-repeatable-iterable | Configure whether to use repeatable streams. | | +| Target Variable a| String | The name of a variable to store the operation's output. | | +| Target Value a| String | An expression to evaluate against the operation's output and store the expression outcome in the target variable. | `#[payload]` | +| Reconnection Strategy a| * <> +* <> | A retry strategy in case of connectivity errors. | | +|=== + +==== Output +[%autowidth.spread] +|=== +| *Type* a| Array of Message of [String] payload and [<>] attributes. The payload contains the element path. +|=== + +=== For Configurations +* <> + +==== Throws +* SFTP:ILLEGAL_PATH +* SFTP:ACCESS_DENIED + + +[[move]] +=== Move +`` + + +Moves the file or directory from the *Source Path* into the *Target Path*. The source path can be either a file or a directory. If it points to a directory, then it will be moved recursively. + +If the target path doesn't exist, and neither does its parent, then a parent folder is created if *Create parent directories* is set to `true`. If *Create parent directories* is set to `false`, then an `SFTP:ILLEGAL_PATH` error is thrown. + +If the target file already exists, then it will be overwritten if *Overwrite* is set to `true`. If *Overwrite* is set to `false`, an `SFTP:FILE_ALREADY_EXISTS` error will be thrown. + +==== Parameters +[%header,cols="20s,20a,35a,20a,5a"] +|=== +| Name | Type | Description | Default Value | Required +| Configuration | String | The name of the configuration to use. | | x +| Source Path a| String | The path to the file to copy. | | x +| Target Path a| String | The target directory. | | x +| Create Parent Directories a| Boolean | Whether or not to attempt to create any parent directories that don't exist. | `true` | +| Overwrite a| Boolean | Whether or not to overwrite the file if the target destination already exists. | `false` | +| Rename To a| String | Name of the moved file. If a value is not provided, the original file name is kept. | | +| Reconnection Strategy a| * <> +* <> | A retry strategy in case of connectivity errors. | | +|=== + + +==== For Configurations. +* <> + +==== Throws +* SFTP:RETRY_EXHAUSTED +* SFTP:ILLEGAL_PATH +* SFTP:FILE_ALREADY_EXISTS +* SFTP:CONNECTIVITY + + +[[read]] +=== Read +`` + + +Obtains the content and metadata of a file at a given path. The operation itself returns a message whose payload is an input stream with the file's content, and the metadata is represented as an `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 provided by the host file system, its behavior might change depending on the SFTP server or its file system. Take that into consideration before relying on this lock. + +This method also makes a best effort to determine the MIME type of the file being read by using the file's extension to make an educated guess. You can also use the output *Encoding* and output *MIME Type* optional parameters to force the encoding and MIME type. + + +==== Parameters +[%header,cols="20s,20a,35a,20a,5a"] +|=== +| Name | Type | Description | Default Value | Required +| Configuration | String | The name of the configuration to use. | | x +| File Path a| String | The path to the file to read.| | x +| Lock a| Boolean | Whether or not to lock the file. Defaults to `false`. | `false` | +| Time Between Size Check a| Number | Wait time between size checks to determine if a file is ready to read. | | +| Time Between Size Check Unit a| Enumeration is one of: + +* NANOSECONDS +* MICROSECONDS +* MILLISECONDS +* SECONDS +* MINUTES +* HOURS +* DAYS | Time unit to use in the wait time between size checks. | | +| Output Mime Type a| String | The MIME type of the payload that this operation outputs. | | +| Output Encoding a| String | The encoding of the payload that this operation outputs. | | +| Streaming Strategy a| * <> +* <> +* non-repeatable-stream | Configure whether to use repeatable streams. | | +| Target Variable a| String | The name of a variable to store the operation's output. | | +| Target Value a| String | An expression to evaluate against the operation's output and store the expression outcome in the target variable. | #[payload] | +| Reconnection Strategy a| * <> +* <> | A retry strategy in case of connectivity errors. | | +|=== + +==== Output +[%autowidth.spread] +|=== +|Type |Binary +| Attributes Type a| <> +|=== + +=== For Configurations +* <> + +==== Throws +* SFTP:FILE_LOCK +* SFTP:RETRY_EXHAUSTED +* SFTP:ILLEGAL_PATH +* SFTP:ACCESS_DENIED +* SFTP:CONNECTIVITY + + +[[rename]] +=== Rename +`` + +Renames the file to which the path points to the value provided in the *New Name* parameter. This argument should not contain any path separator, or an `SFTP:ILLEGAL_PATH` error will be thrown. + + +==== Parameters +[%header,cols="20s,20a,35a,20a,5a"] +|=== +| Name | Type | Description | Default Value | Required +| Configuration | String | The name of the configuration to use. | | x +| Path a| String | The path to the file to rename. | | x +| New Name a| String | The file's new name. | | x +| Overwrite a| Boolean | Whether or not to overwrite the file if the target destination already exists. | `false` | +| Reconnection Strategy a| * <> +* <> | A retry strategy in case of connectivity errors. | | +|=== + + +=== For Configurations +* <> + +==== Throws +* SFTP:RETRY_EXHAUSTED +* SFTP:ILLEGAL_PATH +* SFTP:ACCESS_DENIED +* SFTP:FILE_ALREADY_EXISTS +* SFTP:CONNECTIVITY + + +[[write]] +=== Write +`` + + +Writes the content into the file the path points to. + +If the directory to which the file is attempting to be written doesn't exist, then the operation will either throw an `SFTP:ILLEGAL_PATH` error, or create a new folder, depending on the value of *Create parent directories*. If the file already exists, then the behavior depends on the supplied mode. + +This operation also supports locking depending on the value of the lock argument, and follows the same rules and considerations as described in the read operation. + +NOTE: An additional check is performed if the file already exists, thus the FTP `STAT` command is executed before writing the file. + +==== Parameters +[%header,cols="20s,20a,35a,20a,5a"] +|=== +| Name | Type | Description | Default Value | Required +| Configuration | String | The name of the configuration to use. | | x +| Path a| String | The path of the file to write. | | x +| Content a| Binary | The content to write into the file. Defaults to the current Message payload. | `#[payload]` | +| Create Parent Directories a| Boolean | Whether or not to attempt to create any parent directories that don't exist. | `true` | +| Lock a| Boolean | Whether or not to lock the file. Defaults to `false`. | `false` | +| Write Mode a| Enumeration is one of: + +* OVERWRITE +* APPEND +* CREATE_NEW | A `FileWriteMode`. Defaults to `OVERWRITE` | `OVERWRITE` | +| Reconnection Strategy a| * <> +* <> | A retry strategy in case of connectivity errors. | | +|=== + + +=== For Configurations +* <> + +==== Throws +* SFTP:FILE_LOCK +* SFTP:RETRY_EXHAUSTED +* SFTP:ILLEGAL_PATH +* SFTP:ACCESS_DENIED +* SFTP:ILLEGAL_CONTENT +* SFTP:FILE_ALREADY_EXISTS +* SFTP:CONNECTIVITY +* SFTP:FILE_DOESNT_EXIST + + +== Sources + +[[listener]] +=== On New or Updated File +`` + +Polls a directory and looks for files that have been created in 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. There are three strategies for that: + +* Set the *Auto delete* parameter to `true` to delete each file after it is processed, which causes all files obtained in the next poll to be necessarily new. +* Set the *Move to directory* parameter to move each file to a different directory after it is processed, which achieves the same effect as *Auto delete* but without losing the file. +* Use *Watermark enabled* to pick only files that have been created or updated after the last poll was executed. + +You can also use a matcher for additional filtering of files. + +The *On New Or Updated File* source ignores files that return with an empty attributes list. The list can be empty if the modification time (MDTM) is not enabled by the SFTP server or if the server returns an error when listing the attributes. + +==== Parameters +[%header,cols="20s,20a,35a,20a,5a"] +|=== +| Name | Type | Description | Default Value | Required +| Configuration | String | The name of the configuration to use. | | x +| Directory a| String | The directory in which polled files are contained. | | +| Recursive a| Boolean | Whether or not to also poll files contained in sub directories. | true | +| Matcher a| <> | A matcher used to filter events on files that do not meet the file matching criteria. | | +| Watermark Enabled a| Boolean | Controls whether or not to do watermarking, and if so, if the watermark should consider the file's modification or creation timestamps. Enable this field to have the connector pick only files that were created or updated after the completion of the latest poll. | false | +| Time Between Size Check a| Number | Wait time (in milliseconds) between size checks to determine if a file is ready to read. This allows a file write to complete before processing. When enabled, Mule performs two size checks, waiting the specified time between calls. If both checks return the same value, the file is ready to read. + +You can disable this feature by omitting a value. | | +| Time Between Size Check Unit a| Enumeration is one of: + +* NANOSECONDS +* MICROSECONDS +* MILLISECONDS +* SECONDS +* MINUTES +* HOURS +* DAYS | A TimeUnit which qualifies the *Time between size check* attribute. | | +| Output Mime Type a| String | The MIME type of the payload that this operation outputs. | | +| Output Encoding a| String | The encoding of the payload that this operation outputs. | | +| Primary Node Only a| Boolean | Whether this source should be executed only on the primary node when running in a cluster. | | +| Scheduling Strategy a| scheduling-strategy | Configures the scheduler that triggers the polling. | | x +| Streaming Strategy a| * <> +* <> +* non-repeatable-stream | Configure whether to use repeatable streams. | | +| Redelivery Policy a| <> | Defines a policy for processing the redelivery of the same message. | | +| Reconnection Strategy a| * <> +* <> | A retry strategy in case of connectivity errors. | | +| Auto Delete a| Boolean | Whether to delete each file after processing. | `false` | +| Move To Directory a| String | If provided, each processed file will be moved to a directory that is pointed to by this path. | | +| Rename To a| String | This parameter works in tandem with *Move to directory*. Use this parameter to enter the name of the directory under which to move the file. Do not set this parameter if *Move to directory* hasn't also been set. | | +| Apply Post Action When Failed a| Boolean | Specifies whether any of the post actions (*Auto delete* and *Move to directory*) should also be applied in case the file fails to be processed. If set to `false`, no failed files will be moved or deleted. | `true` | +| Overwrite a| Boolean | Enables you to overwrite the target file when the destination file has the same name. | `false`| +|=== + +==== Output +[%autowidth.spread] +|=== +|Type |Binary +|Attributes Type a| <> +|=== + +=== For Configurations +* <> + + +== Types +[[SftpProxyConfig]] +=== SFTP Proxy Config + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Host a| String | | | x +| Port a| Number | | | x +| Username a| String | | | +| Password a| String | | | +| Protocol a| Enumeration is of: + +* HTTP +* SOCKS5 | | | x +|=== + +[[SecurityConfiguration]] +=== Security Configuration + +Configuring security settings using the SSH Config Override File means you accept the https://docs.mulesoft.com/connectors/introduction/connectors-shared-responsibilities[shared responsibilities] documentation. + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| SSH Config Override File a| String | Path to the file with the SSH override configurations. It supports the following configs: + +* `KexAlgorithms` + +Specifies the comma separated list of key exchange algorithms. +* `Ciphers` + +Specifies the comma separated list of symmetric ciphers. +* `HostKeyAlgorithms` + +Specifies the comma separated list of host key signature algorithms. +* `MACs` + +Specifies the comma separated list of message authentication codes. + +You define the keys in the file you need to override, defaults are taken for the remaining keys. +| | +|=== + +[[Reconnection]] +=== Reconnection + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Fails Deployment a| Boolean | When the application is deployed, a connectivity test is performed on all connectors. If set to `true`, deployment fails if the test doesn't pass after exhausting the associated reconnection strategy. | | +| Reconnection Strategy a| * <> +* <> | The reconnection strategy to use. It overrides the `Fails Deployment` field. So if the reconnection strategy is set to `reconnect-forever`, the deployment never fails. | | +|=== + +[[reconnect]] +=== Reconnect + +[%header%autowidth.spread] +|=== +| Field | Type | Description | Default Value | Required +| Frequency a| Number | How often (in milliseconds) to reconnect. | | +| Count a| Number | How many reconnection attempts to make. | | +| blocking |Boolean |If `false`, the reconnection strategy runs in a separate, non-blocking thread. |`true` | +|=== + +[[reconnect-forever]] +=== Reconnect Forever + +[%header%autowidth.spread] +|=== +| Field | Type | Description | Default Value | Required +| Frequency a| Number | How often (in milliseconds) to reconnect. | | +| blocking |Boolean |If `false`, the reconnection strategy runs in a separate, non-blocking thread. |`true` | +|=== + + +[[PoolingProfile]] +=== Pooling Profile + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Max Active a| Number | Controls the maximum number of Mule components that can be active at one time. When set to a negative value, there is no limit to the number of components that can be active at one time. When *Max active* is exceeded, the pool is exhausted. | 5 | +| Max Idle a| Number | Controls the maximum number of Mule components that can sit idle in the pool at any one time. When set to a negative value, there is no limit to the number of Mule components that can be idle at one time. | 5 | +| Max Wait a| Number | Specifies the number of milliseconds to wait for a pooled component to become available when the pool is exhausted and the *Exhausted action* is set to `WHEN_EXHAUSTED_WAIT`. | 5 | +| Min Eviction Millis a| Number | Determines the minimum amount of time an object can 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. | 1800000 | +| Eviction Check Interval Millis a| Number | Specifies the number of milliseconds between runs of the object evictor. When non-positive, no object evictor is executed. | -1 | +| Exhausted Action a| Enumeration is one of: + +* WHEN_EXHAUSTED_GROW +* WHEN_EXHAUSTED_WAIT +* WHEN_EXHAUSTED_FAIL a| Specifies the behavior of the Mule component pool when the pool is exhausted. Possible values are: + +* `WHEN_EXHAUSTED_FAIL`, which will throw a `NoSuchElementException`. * `WHEN_EXHAUSTED_WAIT`, which will block by invoking `Object.wait(long)` until a new or idle object is available. +* `WHEN_EXHAUSTED_GROW`, which 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, the specified number of milliseconds, after which a `NoSuchElementException` will be thrown. If `maxThreadWait` is a negative value, it will block indefinitely. | WHEN_EXHAUSTED_GROW | +| Initialisation Policy a| Enumeration is one of: + +* INITIALISE_NONE +* INITIALISE_ONE +* INITIALISE_ALL a| Determines how components in a pool should be initialized. The possible values are: + +* INITIALISE_NONE, which means no components will be loaded into the pool at startup. +* INITIALISE_ONE, which will load one initial component into the pool at startup. +* INITIALISE_ALL, which will load all components in the pool at startup. | INITIALISE_NONE | +|=== + +[[ExpirationPolicy]] +=== Expiration Policy + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Max Idle Time a| 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 a| Enumeration is one of: + +* NANOSECONDS +* MICROSECONDS +* MILLISECONDS +* SECONDS +* MINUTES +* HOURS +* DAYS | A time unit that qualifies the *Max idle time* attribute. | | +|=== + +[[SftpFileAttributes]] +=== SFTP File Attributes + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Timestamp a| DateTime | | | x +| Size a| Number | | | x +| Regular File a| Boolean | | false | +| Directory a| Boolean | | false | +| Symbolic Link a| Boolean | | false | +| Path a| String | | | x +| File Name a| String | | | x +|=== + +[[matcher]] +=== Matcher + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Timestamp Since a| DateTime | Files created before this date are rejected. Any timezone specification in this value is ignored and the Mule server’s time zone is used instead. | | +| Timestamp Until a| DateTime | Files created after this date are rejected. Any timezone specification in this value is ignored and the Mule server’s time zone is used instead. | | +| Not Updated In The Last a| Number | Minimum time that should pass since a file was last updated to not be rejected. This attribute works in tandem with *Time unit*. | | +| Updated In The Last a| Number | Maximum time that should pass from when a file was last updated to not be rejected. This attribute works in tandem with *Time unit*. | | +| Time Unit a| Enumeration is one of: + +* NANOSECONDS +* MICROSECONDS +* MILLISECONDS +* SECONDS +* MINUTES +* HOURS +* DAYS | A *Not updated in the last* attributes. + + + Defaults to MILLISECONDS | MILLISECONDS | +| Case Sensitive a| Boolean | Enables you to configure an external file system matcher as case sensitive or insensitive. | true | +| Filename Pattern a| String | A matching pattern to apply on the file name. Supports glob expressions (default) and regex expressions. To use any of the expressions set a prefix, for example, `glob:*.{java, js}` or `regex:[0-9]test.csv`. | | +| Path Pattern a| String | A matching pattern to apply on the file path | | +| Directories a| Enumeration is one of: + +* REQUIRE +* INCLUDE +* EXCLUDE | Match only if the file is a directory | INCLUDE | +| Regular Files a| Enumeration is one of: + +* REQUIRE +* INCLUDE +* EXCLUDE | Match only if the file is a regular file | INCLUDE | +| Sym Links a| Enumeration is one of: + +* REQUIRE +* INCLUDE +* EXCLUDE | Match only if the file is a symbolic link | INCLUDE | +| Min Size a| Number | The minimum file size in bytes. Files smaller than the specified value are rejected. | | +| Max Size a| Number | The maximum file size in bytes. Files larger than the specified value are rejected. | | +|=== + +[[repeatable-in-memory-stream]] +=== Repeatable In Memory Stream + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Initial Buffer Size a| Number | This is the amount of memory to allocate to consume the stream and provide random access to it. If the stream contains more data than can fit into this buffer, then it will be expanded according to the *Buffer size increment* attribute, with an upper limit of *Max in memory size*. | | +| Buffer Size Increment a| Number | This is by how much the buffer size will be expanded if it exceeds its initial size. Setting a value of zero or lower means that the buffer should not expand, and that a `STREAM_MAXIMUM_SIZE_EXCEEDED` error will be raised when the buffer gets full. | | +| Max Buffer Size a| Number | This is the maximum amount of memory to use. If more than the specified maximum is used, then a `STREAM_MAXIMUM_SIZE_EXCEEDED` error will be raised. A value lower or equal to zero means no limit. | | +| Buffer Unit a| Enumeration is one of: + +* BYTE +* KB +* MB +* GB | The unit in which all these attributes are expressed. | | +|=== + +[[repeatable-file-store-stream]] +=== Repeatable File Store Stream + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Max In Memory Size a| Number | Defines the maximum memory that the stream should use to keep data in memory. If more than that is consumed then content is buffered on the disk. | | +| Buffer Unit a| Enumeration, one of: + +* BYTE +* KB +* MB +* GB | The unit in which maxInMemorySize is expressed | | +|=== + +[[RedeliveryPolicy]] +=== Redelivery Policy + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Max Redelivery Count a| Number | The maximum number of times a message can be redelivered and processed unsuccessfully before triggering process-failed-message | | +| Use Secure Hash a| Boolean | Whether to use a secure hash algorithm to identify a redelivered message | | +| Message Digest Algorithm a| String | The secure hashing algorithm to use. If not set, the default is `SHA-256`. | | +| Id Expression a| 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 a| ObjectStore | The object store where the redelivery counter for each message will be stored. | | +|=== + +[[repeatable-in-memory-iterable]] +=== Repeatable In Memory Iterable + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| Initial Buffer Size a| Number | This is the number of instances initially allowed to be kept in memory in order to consume the stream and provide random access to it. If the stream contains more data than can fit into this buffer, then it will be expanded according to the *Buffer size increment* attribute, with an upper limit of *Max in memory size*. Default value is 100 instances. | | +| Buffer Size Increment a| Number | How much the buffer size will expand if it exceeds its initial specified size. Setting a value of zero or lower means that the buffer should not expand, and that a `STREAM_MAXIMUM_SIZE_EXCEEDED` error will be raised when the buffer gets full. Default value is 100 instances. | | +| Max in Memory Instances a| Number | This is the maximum amount of memory to use. If more than the maximum amount is used, then a `STREAM_MAXIMUM_SIZE_EXCEEDED` error will be raised. A value lower or equal to zero means no limit. | | +|=== + + +[[repeatable-file-store-iterable]] +=== Repeatable File Store Iterable + +[%header,cols="20s,25a,30a,15a,10a"] +|=== +| Field | Type | Description | Default Value | Required +| In Memory Objects a| Number | The maximum number of instances to keep in memory. If more than the maximum is required, content starts to buffer to the disk. | | +|=== + +== See Also + +https://help.mulesoft.com[MuleSoft Help Center] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-examples.adoc b/sftp/2.3/modules/ROOT/pages/sftp-examples.adoc new file mode 100644 index 0000000000..448829401e --- /dev/null +++ b/sftp/2.3/modules/ROOT/pages/sftp-examples.adoc @@ -0,0 +1,31 @@ += SFTP Connector Examples - Mule 4 + +To fully benefit from using Anypoint Connector for SFTP (SFTP Connector), see the following examples of configuring the connector operations: + +* xref:sftp-read.adoc[Read a File] + +Configure the *Read* operation to read a file at any point in the flow. +* xref:sftp-write.adoc[Write a File] + +Configure the *Write* operation to write content into the given path on demand. +* xref:sftp-list.adoc[List Files] + +Configure the *List* operation to list the files and folders in the configured directory path. +* xref:sftp-copy-move.adoc[Copy and Move Files] + +Configure the *Copy* and *Move* operations to copy or move files or directories on demand. +* xref:sftp-create-directory.adoc[Create a Directory] + +Configure the *Create Directory* operation to create a directory of a given name. +* xref:sftp-on-new-file.adoc[Trigger a Flow for a New Created or Updated File] + +Configure the *On New or Updated File* source to trigger a flow for a new created or modified file. +* xref:sftp-connection.adoc[Connect to an SFTP Server] + +Configure the SFTP global configuration element to connect to an SFTP server, or to connect to an SFTP server through a proxy. +* xref:sftp-connection-dynamically.adoc[Connect to SFTP Servers Dynamically] + +Configure SFTP Connector to connect dynamically to multiple servers. +* xref:sftp-pooling.adoc[Disable pooling in SFTP Configuration ] + +Disable connection pooling in SFTP Connector configuration to make sure no connection is active if there is nothing to transfer. +* xref:sftp-preferred-authentication.adoc[Configure Preferred Authentication ] + +Configure the preferred authentication for the SFTP Connection. +* xref:sftp-security-configuration-override.adoc[Configure Security Parameters of SSH Connection] + +Override default security configuration of SSH Connection. + +== See Also + +* xref:connectors::introduction/introduction-to-anypoint-connectors.adoc[Introduction to Anypoint Connectors] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-list.adoc b/sftp/2.3/modules/ROOT/pages/sftp-list.adoc new file mode 100644 index 0000000000..1bad67a54e --- /dev/null +++ b/sftp/2.3/modules/ROOT/pages/sftp-list.adoc @@ -0,0 +1,258 @@ += List Files Using the SFTP Connector - Mule 4 +:page-aliases: connectors::sftp/sftp-list.adoc + +Anypoint Connector for SFTP (SFTP Connector) provides a *List* operation that returns a list of messages representing files or folders in the directory path: + +* The path you define in the *Directory path* field can be absolute, or it can be relative to a working directory. +* By default, the operation does not read or list files or folders within any subfolders of the directory path. +* To list files or folders within any subfolders, set the *Recursive* field to *TRUE*. + +== Configure the List Operation in Studio + +To add and configure the *List* operation in Studio, follow these steps: + +. In the *Mule Palette* view, search for `sftp` and select the *List* operation. +. Drag the *List* operation onto the Studio canvas. +. In the *General* tab of the operation configuration screen, click the plus sign (*+*) next to the *Connector configuration* field to access the global element configuration fields. +. Specify the connection information and click *OK*. +. In the *General* tab, set the *Directory path* field to `~/dropFolder` to set the path of the file to list. + +image::sftp-list-operation-1.png[List operation configuration in Studio] + +In the *Configuration XML* editor, the `` configuration looks like this: +[source,xml,linenums] +---- + +---- + +== Examples + +=== Basic use case + +The following XML example lists the folder contents of messages in the directory path without the subfolder contents. The *For Each* and *Choice* components manage each directory in the list differently from the way they manage each file: + +[source,xml,linenums] +---- + + + + + + + + + + + + + + + +---- + +=== Poll a Directory + +You can combine a *Scheduler* source with the SFTP *List* operation to poll a directory to look for new files to process. + + +[NOTE] +For automatic polling, use the SFTP xref:sftp-on-new-file.adoc[On New or Updated File] operation which enables you to optionally set post-processing options to automatically move or delete files. + +In the following poll directory example, a flow lists the contents of a folder once per second. The flow then processes the files one by one, deleting each file after it is processed because there is a *Delete* operation in the *For Each* component. + +The following screenshot shows the flow in Studio: + +image::sftp-list-operation-2.png[Pool a directory flow in Studio] + +To create the flow, follow these steps: + +. In Studio, drag the *Scheduler* component onto the Studio canvas. +. Drag the SFTP *List* operation to the right of *Scheduler*. +. In the *General* tab of the operation configuration screen, click the plus sign (*+*) next to the *Connector configuration* field to access the global element configuration fields. +. Specify the connection information and click *OK*. +. In the *General* tab, set the *Directory path* field to `/config/dropFolder` to set the path of the file to list. +. Drag a *For each* component to the right of the *List* operation. +. Drag a *Flow Reference* component inside the *For each* component. +. Set the *Flow name* field to `processFile` to specify the flow reference that process the files. +. Drag an SFTP *Delete* operation to the right of the *Flow Reference* component. +. Set the *Connector configuration* field to the previously configured connection in the *List* operation. +. Set the *Path* field to `#[payload]`. +. Drag a *Transform Message* component below the first flow. +. Select the new flow and change the *Name* field to `processFile`. +. Drag an SFTP *Read* operation to the left of the *Transform Message* component and set the *Path* field to `#[payload]`. +. Select the *Transform Message* component in the new flow, and in the *Output* view, paste the following DataWeave expression: ++ +[source,dataWeave,linenums] +---- +%dw 2.0 + output application/json + --- + characters: payload.characters.*name map ( + (item, index) -> {name: item} + ) +---- ++ +. Drag a *Logger* component to the right of *Transform Message*. +. Set the *Message* field to `payload`. +. Drag an Objet Store *Store* operation to the right of *Logger*. +. Set the *Key* field to `test-file-' ++ random() as String ++ '.json'`, and *Value* to `payload`. +. Save your Mule application. + +In the *Configuration XML* editor, the configuration looks like this: + +[source,xml,linenums] +---- +?xml version="1.0" encoding="UTF-8"?> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + {name: item} + )]]> + + + + + + + + + +---- + +== Match Filter + +When listing files, use the *File Matching Rules* field, which accepts files that match the specified criteria. This field defines the possible attributes to either accept or reject a file. +These attributes are optional and ignored if you do not provide values for them. Use an `AND` operator to combine individual attributes. + +To configure the field in Studio, set the *File Matching Rules* field to *Edit inline* and complete the desired attributes: + +* *Timestamp since* + +Files created before this date are rejected. Any timezone specification in this value is ignored and the Mule server’s time zone is used instead. +* *Timestamp until* + +Files created after this date are rejected. Any timezone specification in this value is ignored and the Mule server’s time zone is used instead. +* *Not updated in the last* + +Minimum time that should pass since a file was last updated to not be rejected. This attribute works in tandem with *Time unit*. +* *Updated in the last* + +Maximum time that should pass from when a file was last updated to not be rejected. This attribute works in tandem with *Time unit*. +* *Time unit* + +A *Not updated in the last* attributes. Defaults to `MILLISECONDS`. +* *Filename pattern* + +Similar to the current filename pattern filter but more powerful. Glob expressions (default) and regex are supported. You can select which one to use by setting a prefix, for example, `glob:*.{java, js}` or `regex:[0-9]test.csv`. +* *Path pattern* + +Same as *Filename pattern* but applies over the entire file path rather than just a filename. +* *Directories* + +Match only if the file is a directory. +* *Regular files* + +Match only if the file is a regular file. +* *Sym links*` + +Match only if the file is a symbolic link. +* *Min size* + +Inclusive lower boundary for the file size, expressed in bytes. +* *Max size* + +Inclusive upper boundary for the file size, expressed in bytes. + +image::sftp-list-operation-3.png[File Matching Rules field configuration] + +In the *Configuration XML* editor, the configuration looks like this: +[source,xml,linenums] +---- + +---- +=== External File System Matcher + +SFTP Connector enables you to use an external file system matcher. Configure the matcher as case sensitive or insensitive in the *Case sensitive* field. + +image::sftp-list-operation-4.png[Case sensitive field set to TRUE] + +In the *Configuration XML* editor, the `caseSensitive` configuration looks like this: +[source,xml,linenums] +---- + + + +---- + + + + +=== Top-Level, Reusable Matcher + +You can use the file matcher as either a named top-level element that enables reuse or as an inner element that is proprietary to a particular component. + +The following example shows a top-level reusable matcher: + +[source,xml,linenums] +---- + + + + ... + +---- + +=== Inner Nonreusable Matcher + +The following example shows an inner nonreusable matcher: + +[source,xml,linenums] +---- + + + + + ... + +---- + +== See Also + +* xref:sftp-examples.adoc[SFTP Connector Examples] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-on-new-file.adoc b/sftp/2.3/modules/ROOT/pages/sftp-on-new-file.adoc new file mode 100644 index 0000000000..bca8b3a2d0 --- /dev/null +++ b/sftp/2.3/modules/ROOT/pages/sftp-on-new-file.adoc @@ -0,0 +1,38 @@ += Trigger a Flow When a New File Is Created or Modified Example - Mule 4 +:page-aliases: connectors::sftp/sftp-on-new-file.adoc + +include::partial$common-on-new-file.adoc[] + +== Configure the On New or Updated File Operation in Studio + +To add and configure the *On New or Updated File* operation in Studio, follow these steps: + +. In the *Mule Palette* view, search for `sftp` and select the *On New or Updated File* operation. +. Drag the *On New or Updated File* operation onto the Studio canvas. +. In the *General* tab of the operation configuration screen, click the plus sign (*+*) next to the *Connector configuration* field to access the global element configuration fields. +. Specify the connection information and click *OK*. +. Set the *Directory* field to the directory path on which pooled files are contained, for example, `test-data/in`. +. Set the *Auto delete* field to *True*. +. Select the *Watermark* field to enable watermarking. + +image::sftp-newupdated-operation.png[On New or Updated File operation configuration in Studio] + +In the *Configuration XML* editor, the `` configuration looks like this: + +[source,xml,linenums] +---- + + + + + + + + + +---- + +== See Also + +* xref:sftp-examples.adoc[SFTP Connector Examples] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-pooling.adoc b/sftp/2.3/modules/ROOT/pages/sftp-pooling.adoc new file mode 100644 index 0000000000..28564abd91 --- /dev/null +++ b/sftp/2.3/modules/ROOT/pages/sftp-pooling.adoc @@ -0,0 +1,17 @@ += Disable Pooling in the SFTP Connector Configuration + +Disable connection pooling in the Anypoint Connector for SFTP (SFTP Connector) configuration to make sure no connection is active if there is nothing to transfer. + +. In Studio, navigate to the *Global Elements* tab. +. Select the *SFTP Connector* config. +. Click *Edit*. +. In the Global Elements properties tab, click the *Advanced* tab. +. Set *Pooling profile* to *Edit inline*. +. Set the values of *Max active*, *Max idle*, and *Max wait* to `0` to ensure that no connection is active if there is nothing to transfer. + +image::sftp-pooling.png[SFTP Connection pooling configuration in Studio] + +== See Also + +* xref:sftp-examples.adoc[SFTP Connector Examples] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-preferred-authentication.adoc b/sftp/2.3/modules/ROOT/pages/sftp-preferred-authentication.adoc new file mode 100644 index 0000000000..36da9e839e --- /dev/null +++ b/sftp/2.3/modules/ROOT/pages/sftp-preferred-authentication.adoc @@ -0,0 +1,32 @@ += Configure Preferred Authentication + +Anypoint Connector for SFTP (SFTP Connector) enables you to configure preferred authentication methods in the SFTP global configuration of the connector. The following example shows how to configure different authentication methods in Anypoint Studio. + +. In Studio, navigate to the *Global Elements* tab. +. In the Choose Global Type window, type `sftp` in the search bar. +. Select *SFTP Config*. +. Click *OK*. +. Set *Preferred authentication methods* to *Edit inline*. +. Click the plus sign to add one of the valid authentication methods: `GSSAPI_WITH_MIC`, `KEYBOARD_INTERACTIVE`, `PUBLIC_KEY`, or `PASSWORD`. +. Set *Value* to `GSSAPI_WITH_MIC`. +. Complete the remaining connection fields. +. Click *Test Connection...*. +. Click *OK*. + +image::sftp-preferred-authentication.png[SFTP Configuration with preferred authentication field set to GSSAPI_WITH_MIC] + +In the *Configuration XML* editor window, the configuration looks like this: + +[source,xml,linenums] +---- + + + + + + + +---- + +== See Also +* xref:sftp-examples.adoc[] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-read.adoc b/sftp/2.3/modules/ROOT/pages/sftp-read.adoc new file mode 100644 index 0000000000..9eb8b91024 --- /dev/null +++ b/sftp/2.3/modules/ROOT/pages/sftp-read.adoc @@ -0,0 +1,59 @@ += Read a File Using the SFTP Connector Example - Mule 4 +:page-aliases: connectors::sftp/sftp-read.adoc + +Anypoint Connector for SFTP (SFTP Connector) provides a *Read* operation that reads a file at any point in the flow. The operation reads the file in the given path and returns a Mule message with the following attributes: + +* The file's content as the payload +* The file's metadata in the message attributes +* If the file does not exist, you receive an `SFTP:ILLEGAL_PATH` error ++ +Note that the operation does not read directories. + +== Configure the Read Operation in Studio + +To add and configure the *Read* operation in Studio, follow these steps: + +. In the *Mule Palette* view, search for `sftp` and select the *Read* operation. +. Drag the *Read* operation onto the Studio canvas. +. In the *General* tab of the operation configuration screen, click the plus sign (*+*) next to the *Connector configuration* field to access the global element configuration fields. +. Specify the connection information and click *OK*. +. In the *General* tab, set the *File Path* field to the path of the file to read, for example, `#[path]`. +. In the *Advanced* tab, set the *MIME Type* field to `application/xml` and the *Encoding* field to `ISO 10646/Unicode(UTF-8)`. + +The following screenshot shows the *Read* operation configuration: + +.Read operation configuration +image::sftp-read-operation.png[Read operation configuration in Studio] + +In the XML editor, the `` configuration looks like this: +[source,xml,linenums] +---- + +---- + +== Transactions Per Second + +The following table compares the total requests per second (TPS) and average success TPS for the *Read* operation of the SFTP Connector versions: + +[%header%autowidth.spread] +|=== +|Connector version |Mule runtime engine version|Total requests for v1.6.1 |Total requests for v2.0.1 |Average success TPS for v1.6.1 |Average success TPS for v2.0.0 | Percentage of decreased TPS performance +|1.6.1 vs 2.0.0 | 4.4.1 | 301,377.40 | 247,614.40 | 1,674 | 1,375.60 | -18 +|1.6.1 vs 2.0.0 | 4.5.0 | 326,915.80 | 247,296.20 | 1,816 | 1,374 | -24 +|=== + + +// == INCLUDE SHARED READ OP CONTENT FOR FILE, FTP, AND SFTP CONNECTORS +include::partial$common-read-operation.adoc[] + +// == File Locking SHARED BY FTP AND SFTP only +include::partial$common-file-lock.adoc[] + + +== See Also + +* xref:sftp-examples.adoc[SFTP Connector Examples] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-security-configuration-override.adoc b/sftp/2.3/modules/ROOT/pages/sftp-security-configuration-override.adoc new file mode 100644 index 0000000000..878106a5f2 --- /dev/null +++ b/sftp/2.3/modules/ROOT/pages/sftp-security-configuration-override.adoc @@ -0,0 +1,64 @@ += Configure Security Parameters of SSH Connection + +The following example shows how to configure the Anypoint Connector for SFTP (SFTP Connector) to override security parameters using Anypoint Studio. + +== Create a Configuration Override File + +Follow these steps to create the file: + +. Navigate to your `src/main/resources` folder. +. Create a config file, for example, `mule_sshd_config` with the following SSHD content. The file follows the format of an `sshd_config` file: ++ +[source,xml,linenums] +---- +KexAlgorithms ecdh-sha2-nistp521,ecdh-sha2-nistp384,ecdh-sha2-nistp256,diffie-hellman-group18-sha512,diffie-hellman-group17-sha512,diffie-hellman-group16-sha512,diffie-hellman-group14-sha256 +Ciphers aes128-cbc,aes128-ctr,aes192-cbc,aes192-ctr,aes256-cbc,aes256-ctr +HostKeyAlgorithms ssh-rsa,rsa-sha2-256,rsa-sha2-512 +MACs hmac-sha1,hmac-sha2-256,hmac-sha2-512 +---- +image::sftp-override-config-file-contents.png[Contents of the override config file] + +[start=3] +. Configure the keys and values accordingly. If you do not provide a key, then default values are used. + +The following example shows the location of the config file within the `src/main/resources` folder: + +image::sftp-override-config-file-location.png[Location of the override config file] + +== Configure the Override File in Anypoint Studio + +Follow these steps to configure the override file: + +. In Studio, navigate to the *Global Elements* tab. +. In the Choose Global Type window, type `sftp` in the search bar. +. Select *SFTP Config*. +. Click *OK*. +. Go to the *Advanced* tab. +. Under *Security Configuration*, enter `ssh config override file`. +. Enter the path to the file, for example: `${app.home}/mule_sshd_config`. +. Complete the remaining connection fields. +. Click *Test Connection...*. +. Click *OK*. + +image::sftp-override-security-parameters.png[SFTP Configuration with preferred authentication field set to GSSAPI_WITH_MIC] + +In the *Configuration XML* editor window, the configuration looks like this: + +[source,xml,linenums] +---- + + + + +---- + +== Verify the Override File Creation + +Consider the following points when verifying the file creation: + +* Search for the log `Read the config file` and verify that the filename and the configuration values fetched from the file are valid. +* Find ignored configs with the log line `Config keys found but ignored`. +* Check that if the connector is unable to locate the file, then it logs `Couldn't locate config file`. + +== See Also +* xref:sftp-examples.adoc[] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-studio.adoc b/sftp/2.3/modules/ROOT/pages/sftp-studio.adoc new file mode 100644 index 0000000000..771a717501 --- /dev/null +++ b/sftp/2.3/modules/ROOT/pages/sftp-studio.adoc @@ -0,0 +1,131 @@ += Using Anypoint Studio to Configure SFTP Connector 2.2 - Mule 4 + +Anypoint Studio (Studio) editors help you design and update your Mule applications, properties, and configuration files. + +To add and configure a connector in Studio: + +. <>. +. <>. +. <>. +. <>. +. <>. + +When you run the connector, you can view the app log to check for problems in real time, as described in <>. + +If you are new to configuring connectors in Studio, see xref:connectors::introduction/intro-config-use-studio.adoc[Using Anypoint Studio to Configure a Connector]. If, after reading this topic, you need additional information about the connector fields, see the xref:sftp-documentation.adoc[SFTP Connector Reference Reference]. + +[[create-mule-project]] +== Create a Mule Project + +In Studio, create a new Mule project in which to add and configure the connector: + +. In Studio, select *File > New > Mule Project*. +. Enter a name for your Mule project and click *Finish*. + + +[[add-connector-to-project]] +== Add the Connector to Your Mule Project + +Add SFTP Connector to your Mule project to automatically populate the XML code with the connector's namespace and schema location and to add the required dependencies to the project's `pom.xml` file: + +. In the *Mule Palette* view, click *(X) Search in Exchange*. +. In the *Add Dependencies to Project* window, type `sftp` in the search field. +. Click *SFTP Connector* in *Available modules*. +. Click *Add*. +. Click *Finish*. + +Adding a connector to a Mule project in Studio does not make that connector available to other projects in your Studio workspace. + + +[[configure-input-source]] +== Configure a Source + +A source initiates a flow when a specified condition is met. +You can configure one of these sources to use with SFTP Connector: + +* *On New or Updated File* + +Initiates a flow by polling a directory for files that have been created or updated and generates a message for each file found. +* *HTTP Listener* + +Initiates a flow each time it receives a request on the configured host and port. +* *Scheduler* + +Initiates a flow when a time-based condition is met. + +For example, to configure the On New or Updated File source, follow these steps: + +. In the *Mule Palette* view, select *On New or Updated File*. +. Drag *On New or Updated File* to the Studio canvas. +. On the *On New or Updated File* configuration screen, optionally change the value of the *Display Name* field. +. Specify a value for the *Path* field. +. Click the plus sign (*+*) next to the *Connector configuration* field to configure a global element that can be used by all instances of *On New or Updated File* in the app. +. On the *General* tab, specify the connection information for the connector. +. Set the *Host* field to specify the SFTP server host, for example, `localhost` or `192.168.0.1`. +. Click *Test Connection* to confirm that Mule can connect with the specified server. +. Click *OK*. +. On the *On New or Updated File* configuration screen, specify a *Scheduling Strategy* value and optionally complete other fields. + +[[add-connector-operation]] +== Add a Connector Operation to the Flow + +When you add a connector operation to your flow, you immediately define a specific operation for that connector to perform. + +To add an operation for SFTP Connector, follow these steps: + +. In the *Mule Palette* view, select *SFTP* and then select the desired operation. +. Drag the operation onto the Studio canvas and to the right of the source. + +The following screenshot shows the SFTP Connector operations in the Mule Palette view of Anypoint Studio: + +.SFTP Connector Operations +image::sftp-operations.png[SFTP Connector Operations] + +[[configure-global-element]] +== Configure a Global Element for the Connector + +When you configure a connector, it’s best to configure a global element that all instances of that connector in the app can use. Configuring a global element requires you to configure the SFTP server connection. + +To configure the global element for SFTP Connector, 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* as the 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`. +. 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*. + +The following screenshot shows the SFTP Connector *Global Element Configuration* window in Anypoint Studio: + +.SFTP Connector Global Element Configuration +image::sftp-global-configuration-with-required-lib.png[SFTP Connector Global Element Configuration] + +In the XML editor, the configuration `sftp:config` looks like this: +[source,xml,linenums] +---- + + + +---- + +[[view-app-log]] +== View the App Log + +To check for problems, you can view the app log as follows: + +* If you’re running the app from Anypoint Platform, the output is visible in the Anypoint Studio console window. +* If you’re running the app using Mule from the command line, the app log is visible in your OS console. + +Unless the log file path is customized in the app’s log file (`log4j2.xml`), you can also view the app log in the default location `MULE_HOME/logs/.log`. + + +== See Also + +* xref:connectors::introduction/introduction-to-anypoint-connectors.adoc[Introduction to Anypoint Connectors] +* xref:connectors::introduction/intro-config-use-studio.adoc[Using Anypoint Studio to Configure a Connector] +* xref:sftp-documentation.adoc[SFTP Connector Reference] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-write.adoc b/sftp/2.3/modules/ROOT/pages/sftp-write.adoc new file mode 100644 index 0000000000..09a71d0035 --- /dev/null +++ b/sftp/2.3/modules/ROOT/pages/sftp-write.adoc @@ -0,0 +1,71 @@ += Write a File Using the SFTP Connector Example - Mule 4 +:page-aliases: connectors::sftp/sftp-write.adoc + +Anypoint Connector for SFTP (SFTP Connector) provides a *Write* operation that writes content into the given path on demand. + +== Configure the Write Operation in Studio + +To add and configure the *Write* operation in Studio, follow these steps: + +. In the *Mule Palette* view, search for `sftp` and select the *Write* operation. +. Drag the *Write* operation onto the Studio canvas. +. In the *General* tab of the operation configuration screen, click the plus sign (*+*) next to the *Connector configuration* field to access the global element configuration fields. +. Specify the connection information and click *OK*. +. In the *General* tab, set the *Path* field to `output.csv` to set the path of the file to write. + +By default, the connector writes whatever is in the message payload. + +image::sftp-write-operation-1.png[Write operation configuration in Studio] + +In the *Configuration XML* editor, the `` configuration looks like this: +[source,xml,linenums] +---- + +---- + + +== Use Embedded DataWeave Transformations + +If you place a *Transform Message* component before the *Write* operation, the message payload changes, and that impacts the operation that is placed after the *Write* operation. +Therefore, if the payload is in a different format and you need to transform it before writing it, you can place the transformation inside the *Content* field of the *Write* operation to generate content to be written without affecting the message in transit. + +The following example places the DataWeave transformation in the *Content* field: + +image::sftp-write-operation-2.png[Write operation configuration in Studio with Content field] + +In the *Configuration XML* editor, the configuration looks like this: +[source,xml,linenums] +---- + + #[%dw 2.0 + output application/csv + --- + payload.customers.email + ] + + +---- + +== Write into Directories + +Because the *Write* operation fails by default if you set nonexistent directories in the *Path* field, set the *Create parent directories* field to *True (Default)* to automatically create any missing directories. + +The following example shows that if any of the `a`, `b`, or `c` directories set in the *Path* field do not exist, the connector creates them: + +image::sftp-write-operation-3.png[.Write operation configuration with Create parent directories] + +In the *Configuration XML* editor, the configuration looks like this: + +[source,xml] +---- + +---- + +// INCLUDE FOR THESE SECTIONS: +// == Writing to Existing Files +// == Locks +include::partial$common-write.adoc[] + +== See Also + +* xref:sftp-examples.adoc[SFTP Connector Examples] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/sftp/2.3/modules/ROOT/pages/sftp-xml-maven.adoc b/sftp/2.3/modules/ROOT/pages/sftp-xml-maven.adoc new file mode 100644 index 0000000000..afd6935106 --- /dev/null +++ b/sftp/2.3/modules/ROOT/pages/sftp-xml-maven.adoc @@ -0,0 +1,73 @@ + += SFTP Connector XML and Maven Support - Mule 4 + +Although you can manually code a Mule app in XML, it is more efficient to use Anypoint Studio. + +If you manually code a Mule runtime engine (Mule) app in XML, either from the Anypoint Studio XML editor or from a text editor, you can get access to the connector in your app by adding reference statements to both your XML Mule flow and the Apache Maven `pom.xml` file. + +When you add the connector in Studio, Studio automatically populates the XML code with the connector's namespace and schema location. It also adds a dependency to the `pom.xml` file. + +== Add a Namespace for the Connector + +Paste the following code inside the `` tag of the header of your configuration XML: + +[source,xml,linenums] +---- +http://www.mulesoft.org/schema/mule/sftp +http://www.mulesoft.org/schema/mule/sftp /current/mule-sftp .xsd +---- + +This example shows how the namespace statements are placed in the `` XML block: + +[source,xml,linenums] +---- + +---- + + + +== Add a POM File Dependency + +The Apache Maven `pom.xml` file generated by Anypoint Studio contains dependencies for a Mule app. If you code a Mule app manually, include this XML snippet in your `pom.xml` file to enable access to this connector: + +[source,xml,linenums] +---- + + org.mule.connectors + mule-sftp-connector + x.x.x + mule-plugin + +---- + + +Replace `x.x.x` with the version that corresponds to the connector you are using. + +To obtain the most up-to-date `pom.xml` file information: + +. Go to https://www.mulesoft.com/exchange/[Anypoint Exchange]. +. In Exchange, click *Login* and supply your Anypoint Platform username and password. +. In Exchange, search for `sftp connector`. +. Select the connector. +. Click *Dependency Snippets* near the upper right of the screen. + +== See Also + +* xref:connectors::introduction/introduction-to-anypoint-connectors.adoc[Introduction to Anypoint Connectors] +* https://help.mulesoft.com[MuleSoft Help Center] diff --git a/sftp/2.3/modules/ROOT/partials/common-file-lock.adoc b/sftp/2.3/modules/ROOT/partials/common-file-lock.adoc new file mode 100644 index 0000000000..d87b4ff250 --- /dev/null +++ b/sftp/2.3/modules/ROOT/partials/common-file-lock.adoc @@ -0,0 +1,11 @@ +== File Locks + +File system level locks are not possible in FTP or SFTP, so each operation uses a Mule lock that protects only the file from other flows in the same Mule application. These locks do not protect the file from external processes. However, if the Mule application is running on a cluster, the lock is distributed. + +The file lock is automatically released when any of the following occurs: + +* The Mule flow that locked the file ends +* The file content has been fully read + +[NOTE] +If the file is already locked by someone else, the connector cannot unlock it, resulting in a `FTP:FILE_LOCK` error. diff --git a/sftp/2.3/modules/ROOT/partials/common-on-new-file.adoc b/sftp/2.3/modules/ROOT/partials/common-on-new-file.adoc new file mode 100644 index 0000000000..f210467ce1 --- /dev/null +++ b/sftp/2.3/modules/ROOT/partials/common-on-new-file.adoc @@ -0,0 +1,9 @@ +Anypoint Connectors for File, FTP, and SFTP provide an *On New or Updated File* operation that polls a directory for files that have been created or updated. A message is generated for each file that is found. + +The following strategies determine that a file is new: + +* Set the *Auto delete* field to *True* to delete each file after it is processed, which causes all files obtained in the next poll to be considered new. +* Set the *Move to directory* field to move each file to a different directory after it is processed, which achieves the same effect as *Auto delete* but without erasing the file. +* Set the *Watermark* field to pick only files that have been created or updated after the last poll was executed. + +You can also use a matcher for additional filtering of files. diff --git a/sftp/2.3/modules/ROOT/partials/common-read-operation.adoc b/sftp/2.3/modules/ROOT/partials/common-read-operation.adoc new file mode 100644 index 0000000000..fb1b4e839d --- /dev/null +++ b/sftp/2.3/modules/ROOT/partials/common-read-operation.adoc @@ -0,0 +1,9 @@ +== MIME Types and Encoding + +Each connector tries to determine a file’s MIME type from its extension. You can force the MIME type to a different value with the *MIME Type* (`outputMimeType`) parameter. + +The same process works for encoding. By default, the connector assumes that the default encoding in the Mule runtime matches the MIME type of the file, however, you can set the encoding through the *Encoding* (`outputEncoding`) parameter. + +== Why MIME Types Matter + +DataWeave expressions are embeddable inside operations that generate payloads and other values. Having the correct MIME type set helps DataWeave auto-assign types and also generate the correct outputs. Also, maximizing the use of DataSense’s functionality improves the user experience. diff --git a/sftp/2.3/modules/ROOT/partials/common-write.adoc b/sftp/2.3/modules/ROOT/partials/common-write.adoc new file mode 100644 index 0000000000..1fa053e91c --- /dev/null +++ b/sftp/2.3/modules/ROOT/partials/common-write.adoc @@ -0,0 +1,18 @@ +== Write to Existing Files +//INCLUDED IN file-write, ftp-write, and sftp-write adoc files + +When writing content to a file, set the *Write Mode* field to any of the following modes: + +* *OVERWRITE (Default)* + +If the file exists, overwrite it completely. +* *APPEND* + + If the file exists, add its content to the end of an existing file. +* *CREATE_NEW* + +Create a new file. If the file already exists, then you receive an error. + +== Locks + +The *Write* operation supports locking similar to the *Read* operation. The main difference is that the lock releases automatically after the *Write* operation finishes. Set the *Lock* field to any of the following modes: + +* *TRUE* +* *FALSE (Default)*