# SFTP
{% hint style="info" %}
The following documentation is for **SFTP v1.4.11** *(BDK)*.
{% endhint %}
## Overview
SFTP (Secure File Transfer Protocol) provides secure file transfer capabilities for safe data exchange. This integration enables automated file uploads, downloads, directory management, and secure data transmission workflows. Ensure secure file operations and maintain data integrity during transfers.
## Prerequisites
### 1. Required Books
The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:
* **SFTP**
#### How to Add the Book(s)
1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on **Install** or **Add Connection** to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.
## Connectivity
This section outlines the available methods for connecting to the Book, along with the required configuration details for each.
### Connect using Hostname, Port, Username and Password
Connect to an SFTP server.
| Label | Description | Type |
| -------- | -------------------------------- | ----------- |
| Hostname | The hostname of the SFTP server. | `text` |
| Port | The port of the SFTP server. | `text` |
| Username | The username for authentication. | `text` |
| Password | The password for authentication. | `sensitive` |
### Configuration
The following table details all the available configuration options for this book.
| Concept | Description | Type | Default Value |
| -------------------- | -------------------------------------------- | -------- | ------------- |
| `connection timeout` | Get the connection timeout value in seconds. | `number` | (no default) |
| `max retry attempts` | Get the value of the attempts. | `number` | (no default) |
| `base retry delay` | Get the value of the base delay. | `number` | (no default) |
Configuration can be set or retrieved as shown in the following examples:
## Procedures
### to copy an item to a folder
Copy an item to a folder
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | -------- | ------------- |
| `item` | The item (file or folder) to copy | `sftp file reference` or `sftp folder reference` | Yes | (no default) |
| [`folder`](#sftp-folder-reference) | The folder to copy the item to | `sftp folder reference` | Yes | (no default) |
| `conflict behavior` | The behavior to use on conflict scenarios. It should be one of the following values: ('fail', 'replace', 'rename') | `text` | No | fail |
**Examples**
Copy a file on the SFTP server
```generic
copy the new file to the copydestination
the conflict behavior is "replace"
```
### to create a (folder) in another folder
Create a (folder) in another folder
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | ----------------------- | -------- | ------------- |
| [`another folder`](#sftp-folder-reference) | The folder to create the (folder) in | `sftp folder reference` | Yes | (no default) |
| `folder name` | The name of the (folder) to create | `text` | Yes | (no default) |
| `conflict behavior` | The behavior to use on conflict scenarios. It should be one of the following values: ('fail', 'replace', 'rename') | `text` | No | fail |
**Output Concepts**
| Concept | Description | Type |
| ---------------------------------- | ---------------------------------------- | ----------------------- |
| [`folder`](#sftp-folder-reference) | a folder reference to the created folder | `sftp folder reference` |
**Examples**
Create a directory on the SFTP server
```generic
get a folder at "/dir1/dir2"
create a folder in the folder
the folder name is "a-folder"
the conflict behavior is "rename"
```
### to delete an item
Delete an item (file or folder)
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ------- | ----------------------------------- | ------------------------------------------------ | -------- | ------------- |
| `item` | The item (file or folder) to delete | `sftp file reference` or `sftp folder reference` | Yes | (no default) |
**Examples**
Delete a file from the SFTP server
```generic
get a folder at "/dir1/dir2"
get the folder's items whose name is "one.txt"
use the first item as the document
delete the document
```
### to download a file
Download a file
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ------------------------------ | ------------------------------------------ | --------------------- | -------- | ------------- |
| [`file`](#sftp-file-reference) | The file reference to the file to download | `sftp file reference` | Yes | (no default) |
**Output Concepts**
| Concept | Description | Type |
| -------- | ------------------------ | ------ |
| `answer` | the file as an IO object | `file` |
**Examples**
Download a file from the SFTP server
```generic
get the folder's items
use the first item as the testing file
download the testing file
```
### to get a (folder) at a path
Get a reference to a folder.
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ------- | ---------------------- | ------ | -------- | ------------- |
| `path` | The path to the folder | `text` | Yes | (no default) |
**Output Concepts**
| Concept | Description | Type |
| ---------------------------------- | ------------------ | ----------------------- |
| [`folder`](#sftp-folder-reference) | a folder reference | `sftp folder reference` |
**Examples**
Get a folder at a path.
```generic
get a folder at "/dir1/dir2"
```
### to get a (root folder)
Get a reference to the root folder.
**Output Concepts**
| Concept | Description | Type |
| --------------------------------------- | ------------------ | ----------------------- |
| [`root folder`](#sftp-folder-reference) | a folder reference | `sftp folder reference` |
**Examples**
Get the root folder
```generic
get a root folder
```
### to get some (folder's items)
Get items from a folder.
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ---------------------------------- | ------------------------------------------------- | ----------------------- | -------- | ------------- |
| [`folder`](#sftp-folder-reference) | The folder reference from which to list the items | `sftp folder reference` | Yes | (no default) |
**Output Concepts**
| Concept | Description | Type |
| ---------------- | ------------------------------------------------------------------- | ------------------------------------------------ |
| `folder's items` | a list of Items (file or folder) containing the items in the folder | `sftp file reference` or `sftp folder reference` |
**Examples**
List files in a directory on the SFTP server
```generic
get a folder at "/dir1/dir2"
get the folder's items
```
List files in a directory on the SFTP server with a filter expression
```generic
get a folder at "/dir1/dir2"
get the folder's items whose name is not "one.txt"
```
### to move an item to a folder
Move an item to a folder
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | -------- | ------------- |
| `item` | The item (file or folder) to move | `sftp file reference` or `sftp folder reference` | Yes | (no default) |
| [`folder`](#sftp-folder-reference) | The folder to move the item to | `sftp folder reference` | Yes | (no default) |
| `conflict behavior` | The behavior to use on conflict scenarios. It should be one of the following values: ('fail', 'replace', 'rename') | `text` | No | fail |
**Examples**
Move a file on the SFTP server
```generic
move the new file to the movedestination
the conflict behavior is "replace"
```
### to rename an item to a name
Rename an item (file or folder) to a given name
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | -------- | ------------- |
| `item` | The item (file or folder) to rename | `sftp file reference` or `sftp folder reference` | Yes | (no default) |
| `name` | The new name of the item | `text` | Yes | (no default) |
| `conflict behavior` | The behavior to use on conflict scenarios. It should be one of the following values: ('fail', 'replace', 'rename') | `text` | No | fail |
**Examples**
Rename a file on the SFTP server
```generic
get a folder at "/dir1/dir2"
get the folder's items whose name is "one.txt"
use the first item as the new document
rename the new document to "the-renamed-file.txt"
the conflict behavior is "rename"
```
### to upload a (file) to a folder
Upload a file to a folder
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------- | -------- | ------------- |
| `file` | The file to upload | `file` | Yes | (no default) |
| [`folder`](#sftp-folder-reference) | The folder to upload the file to | `sftp folder reference` | Yes | (no default) |
| `file name` | The name of the file to upload | `text` | Yes | (no default) |
| `conflict behavior` | The behavior to use on conflict scenarios. It should be one of the following values: ('fail', 'replace', 'rename') | `text` | No | fail |
**Output Concepts**
| Concept | Description | Type |
| ------------------------------ | ------------------------------------- | --------------------- |
| [`file`](#sftp-file-reference) | a file reference to the uploaded file | `sftp file reference` |
**Examples**
Upload a file to the SFTP server
```generic
the document
upload the document to the folder
the file name is "juan.txt"
the conflict behavior is "rename"
```
## Concepts
### Sftp file reference
Contains all information required to identify a file within a storage system
| Field Name | Description | Type |
| ----------- | ----------------------------- | ------------------ |
| `path` | The path of the file | `text` |
| `file_name` | The name of the file | `text` |
| `size` | The size of the file in bytes | `optional[number]` |
| `extension` | The file extension | `optional[text]` |
| `type` | The type of the SftpItem | `optional[text]` |
| `name` | The name of the item | `optional[text]` |
### Sftp folder reference
Contains all information required to identify a folder within a storage system
| Field Name | Description | Type |
| ------------- | ------------------------ | ---------------- |
| `path` | The path of the folder | `text` |
| `folder_name` | The name of the folder | `text` |
| `type` | The type of the SftpItem | `optional[text]` |
| `name` | The name of the item | `optional[text]` |