Skip to main content
Feedback

SFTP operation

The SFTP operations define how to interact with your SFTP server and represent a specific action to be performed against a specific file.

Create a separate operation component for each action/object combination your integration requires.

The SFTP operations support the following actions:

  • Inbound: Read, List, Listen
  • Outbound: Write, Delete
note

When you use the Write and Delete operations, multiple listener executions are triggered by design.

Options tab

Select a connector action, then use the Import Wizard to select the object to integrate. When you configure an action, the following fields appear on the Options tab.

Connector Action (All operations) - Refers to the action type selected in connector configuration. Auto-populated by the Boomi Enterprise Platform.

Object (All operations) - Defines the object with which you want to integrate and which was selected in the Import Wizard. The types of objects you can import in most operations include:

File - Unstructured content of the files.

File Metadata - Structured metadata of the files without the file content.

Request Profile (Write, Delete) - The request profile highlights the format (Structured and Unstructured) in which the File is to be processed. By default, the format is Unstructured.

Response Profile (Read, Write, List, Listen) - The response profile highlights the format (Structured and Unstructured) in which the response is to be processed. The List operation supports structured and unstructured responses since it allows you to get Files or File Metadata depending on the Object you import.

Tracking Direction - Select the document tracking direction for the operation, either Input Documents or Output Documents. This setting enables you to choose which document appears in Process Reporting. Start steps always track output documents regardless of your selection.

note

If the tracking direction is read-only, the feature to change the direction is either unavailable or the developer set the configuration to read-only. The default value you see shows you which document appears in Process Reporting.

Return Application Error Responses - This setting controls whether an application error prevents an operation from completing:

  • If you clear the setting, the process stops and reports the error on the Process Reporting page.
  • If you select the setting, processing continues and passes the error response to the next component processed as the connection output.

Action After Read (Read) - Specify how to handle files on the SFTP server after successful retrieval. Leave files unchanged (None), move them to another directory (Move), delete them (Delete), or rename them (Rename).

Move to Directory (Read) - The destination directory path where files will be moved after successful retrieval. This field is overrideable per document via the Dynamic Operation Properties tab.

New Filename (Read) - Enter the new name for the file you want to rename, without including any special characters or path information.

Include all metadata (Write, List) - Refers to the option to include all metadata as tracked properties, including the JSON objects: File Name, File content, and Last Modified Date. If cleared, only the File Content (File Name and Directory properties) and Remote Directory are returned in the file format as available on the SFTP server.

note

If this option is selected for the List operation, the returned output will be in JSON format irrespective of the file format on the SFTP server. Otherwise, the output will be returned in the same file format as available on the server.

Attention: The output may contain special characters when executing the List operation with the Include all metadata option. Example: Every new line in the source text file gets printed as a newline character "\n" in the output. The images used in the PDF file might be replaced with a set of special characters in the output. Therefore, if the metadata option is used, it is recommended that unwanted characters in the output be filtered for further processing.

  • For the Write operation, the Include all metadata check box will be available in the Import Wizard.

Action if File Exists (Write) - Specifies how the operation behaves if the file name already exists in the Remote Directory on the SFTP server. Default value is ERROR.

  • Select Create unique name to append a number to the file name by the connector to make it unique.
  • Select Overwrite to replace the existing content with the new one.
  • Select Append to concatenate the new content at the end of the existing one.
  • Select Generate error to generate an error.

Staging Directory (Optional) (Write) - Specifies the temporary directory (absolute or relative directory path) to put a file before being moved to the Remote Directory.

  • If specified, the connector uses the default working directory configured as the base folder on the SFTP server.
  • If not specified, the file is created directly in the Remote Directory.

Temporary Extension (Optional) (Write) - Refers to a temporary extension (for example, .tmp or tmp) to append to the file name until the file is created in the Remote Directory. To avoid overwriting existing files, the connector guarantees that the temporary file name is unique when creating files.

Target File Name (Optional) (Write) - Specify the target file name, if Create unique name is selected for Action if File Exists. It can be a combination of one or more of the following variables:

  • Alphanumeric string
  • $BASE, the base file name of the input file.
  • $EXTENSION, the extension of the input file.
  • $DATE, today's date in MMDDYYYY format.
  • $TIME, current time in HHMMSS.SSS format.
  • $UUID, a randomly generated unique id.

For example, BASE_$DATE.$EXTENSION will generate a target file name, example_09142023.csv, where the input document is example.csv. If left empty, the target file name will be the same as the source file name.

Temporary File Name (Optional) (Write) - Specify the temporary file name, if Create unique name is selected for Action if File Exists. The file naming convention remains the same as the Target File Name.

Maximum Number of Files to Return (List) - Refers to the option, if checked, failed operations will not be reported in Manage, allowing you to act on them in your process. Enter -1 to return as many files as possible.

Recursive Listing of Directory (List) - Refers to the option, if selected, that will list all the files and directories of the root level as well as files one level deeper. The default behavior is to only list the files and directories of the root level.

Append (Write) - Refers to the option to update the existing data by including the new data.

  • If selected, the connector updates existing data to include new data.
  • If cleared, the connector overwrites the existing data.

Create directory if it doesn't exist (Write) - Refers to the selected option, the connector creates a directory (if it does not already exist) according to what is specified in the connection or document property. The default value is false.

Sub Directory (Listen) - Specify the sub directory where the Listen operation listens for events. Listen builds the sub directory by combining the Remote Directory from the connection with this Sub Directory. This field is optional and if not provided, you must specify a Remote Directory in the connection.

Polling Interval (Listen) - Sets the interval between each poll cycle (in milliseconds) on the directory. The default is 60000 milliseconds (1 minute).

Is Singleton (Listen) - When set to true, the basic runtime invokes the isSingleton method of the connector operation, and singleton mode is activated if the method returns true.

Include Create events (Listen) - If selected, Listen retrieves any new file created in the listen directory (the Sub Directory in the connection).

Include Modify events (Listen) - If selected, Listen retrieves any modified file in the listen directory (the Sub Directory in the connection).

Include Delete events (Listen) - If selected, Listen submits an event for any deletion occurring in the listen directory (the Sub Directory in the connection). An event for delete does not include the content of the deleted file.

Common Profile Generation Steps (All operations)

  1. Create an SFTP connector operation component.
  2. Click the Import button.
  3. In the Import Wizard, specify the required basic runtime details and click the Next button.
note

For the Write operation, you can see the Include all metadata check box (optional) available during the import action.

  1. Select the Object Type.
  2. Click the Next button. The selected object and profile details will be displayed.

Read

Read is an inbound action that fetches the content of a file at a given location. Enter the details of the file you want to retrieve from the SFTP server. When using Read to download a file from the server, the file name (ID) must be specified as the parameter. The remote directory in which the file is located can optionally be provided as a document property or connection property. If the remote directory is not provided, the connector uses the default working directory configured as the base folder on the SFTP server.

note
  • When creating a new file, use File Name and Remote Directory as the document property.
  • Import is required to set ID as the file name.
  • There cannot be more than one file with the same name (ID) in a directory.
  • The File Name (ID) should be set as a parameter for successful operation. If not specified, the connector displays an error.
  • Read does not include timestamp info in the payload.
  • Output will always track File Name, Remote Directory, and Last Modified Date

Write

Write is an outbound action to either upload and create a new file in the specified remote directory. Although one SFTP command per file needs to be executed, Write provides batch support since the same SFTP session can be shared for creating more than one file. If the file already exists the connector utilizes the "Action if File Exists" configuration to determine what the operation should do next. This allows for operation reuse across all types of Write operations.

If the Write operation is successful, the file is uploaded and added to the server, and the connector returns a JSON document with information about the file. The file information includes the name, the ID, the user who created the file, when the file was last modified, and other information.

note
  • When creating a new file, use File Name and Remote Directory as the document property.
  • Import is required to get uploaded file metadata and successfully complete the operation.

List

List is an inbound action that gets a list of files in the remote directory based on specific criteria. You can look up File or File Metadata objects in the SFTP server. After successfully executing this operation, the connector produces one JSON document for each file in the specified disk directory. After you select the List action and use the Import Wizard, the operation component page contains configuration options to add filters and set parameters to limit the results.

note
  • This operation does not have a request profile. It returns a response profile for each file containing a JSON object describing the file's metadata, such as File Name, Directory, Created Date, Modified Date, and File Size, and indicates if the file is a directory.
  • If the file or metadata cannot be read, the operation returns a single document with all resulting errors.
  • The List operation for a Directory object can be turned on/off with the Recursive Listing of Directory check box in the operation. The default behavior for recursive listing will return the top level and one level down files, as long as the level down has permissions to traverse. Consequently, if you want to restrict the search to just the top level, you can set the permissions accordingly.

On the Filters tab, you can refine the query by applying the required filter and defining expressions to create the required list logic for the following fields:

Filters

  • Filter Name - Specify a name for the filter expression.
  • Field - Select the criteria to perform the file search. File search can be performed based on fileName, fileSize, modifiedDate, and isDirectory.
    • If the Field value is set as “modifiedDate”, you must set date format mandatory as a connector parameter for successful processing.
    • For Date, the input format is “yyyy-MM-dd'T'HH:mm:ssZZ”, e.g., 2025-03-23T15:18:38-0600
  • Operator - Specify the operator value for the selected search criteria. Based on the search criteria value, operator options will vary as listed below.
    • fileName - Regex match, Wildcard Match, Equals, Does not Equal, Less Than, Greater Than
    • fileSize (in bytes) - Equals, Does not Equal, Less Than, Greater Than.
    • modifiedDate - Equals, Does not Equal, Less Than, Greater Than
    • isDirectory - Equals, Does not Equal (only for File Metadata object)
note

Only one filter expression can be created. If you need to set multiple filter expressions, you need a separate connection for each. The SFTP connector does not allow nested expressions in query strings. The filter expression can also be created with AND/OR Logical Sub-Group using the Filter - Add Logical Sub-Group option.

Delete

Delete is an outbound action that deletes a file from a remote directory in the SFTP server by providing the file name and file directory if you imported a File object. This operation returns an exception if the file name specified is invalid and does not match the ID. If the file directory is not specified, the connector will search for the file in the home directory of the SFTP server and will not return an error message if the file is not found.

If you imported a Directory, you can delete a directory and optionally recursively delete all of the directory contents. Each file that is deleted for this operation will be logged in the process log.

Warning

If the Delete Recursively check box is selected, the entire contents of the directory and its subdirectories will be deleted. The connector does not provide a means to undo this action.

Delete tracks input by default and returns the input profile and ID.

Listen

The Listen operation listens to events in the root directory of the remote SFTP server. This operation allows listening to file creation, file deletion, or any modification of an existing file in the SFTP server remote directory events.

note

This operation does not have a request profile.

note

The Listen operation on runtime cloud works only when you have an execution worker enabled for the respective cloud attachment. Verify that execution workers are enabled for your attachment and the status of the execution workers. Contact your runtime cloud owner or account representative for assistance.

Archiving tab

See the topic Connector operation’s Archiving tab for more information.

Tracking tab

See the topic Connector operation’s Tracking tab for more information.

Caching tab

See the topic Connector operation’s Caching tab for more information.

On this Page