# AWS S3

{% hint style="info" %}
The following documentation is for **AWS S3 v1.6.4** *(BDK)*.
{% endhint %}

## Overview

Amazon S3 (Simple Storage Service) provides scalable object storage with industry-leading durability and availability. This integration enables automated file uploads, downloads, bucket management, and data archiving workflows. Leverage AWS's robust cloud storage infrastructure for secure and scalable data management.

## 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:

* **AWS S3**

#### 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 <kbd>**Install**</kbd> or <kbd>**Add Connection**</kbd> 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 AWS Access key ID, AWS Secret Access Key, AWS Region, AWS Role ARN and AWS External ID

Assumes a role using the provided AWS credentials.

| Label                 | Description                                                                | Type        |
| --------------------- | -------------------------------------------------------------------------- | ----------- |
| AWS Access key ID     | The AWS Access Key ID for the initial authentication.                      | `text`      |
| AWS Secret Access Key | The AWS Secret Access Key for the initial authentication.                  | `sensitive` |
| AWS Region            | The AWS Region for the initial authentication.                             | `text`      |
| AWS Role ARN          | The ARN of the role to assume.                                             | `text`      |
| AWS External ID       | An optional external ID that might be required by the role's trust policy. | `sensitive` |

### Connect using AWS Access key ID, AWS Secret Access Key and AWS Region

Connects to an API using the provided API key.

| Label                 | Description               | Type        |
| --------------------- | ------------------------- | ----------- |
| AWS Access key ID     | The AWS Access Key ID     | `text`      |
| AWS Secret Access Key | The AWS Secret Access Key | `sensitive` |
| AWS Region            | The AWS Region            | `text`      |

## Procedures

### to copy an item to a folder

Create a copy of an item in a folder.

**Input Concepts**

| Concept                          | Description                                                                                                        | Type                                         | Required | Default Value |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | -------- | ------------- |
| `item`                           | The item (file or folder) to copy                                                                                  | `s3 file reference` or `s3 folder reference` | Yes      | (no default)  |
| [`folder`](#s3-folder-reference) | The folder to copy the item to                                                                                     | `s3 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 an item to new folder in AWS S3

```generic
get a folder at "bucket_name/"
use the above as the folder
get some folder's items with
    the folder is the folder
    the path prefix is "kognitos"
use the above as the references
get the first reference as the item
get a folder at "bucket_name/google"
use the above as the folder
copy item to the folder with
    the item is the item
    the folder is the folder
```

### to create a (folder) in another folder

Create a folder in another folder.

**Input Concepts**

| Concept                                  | Description                                                                                                        | Type                  | Required | Default Value |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------- | -------- | ------------- |
| [`another folder`](#s3-folder-reference) | The folder to create the (folder) in                                                                               | `s3 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`](#s3-folder-reference) | a folder reference to the created folder | `s3 folder reference` |

**Examples**

Create a folder in another folder in AWS S3

```generic
get a folder at "bucket_name/google"
use the above as the another_folder
the name is "data"
create a folder in another folder with
    the another folder is the another_folder
    the folder name is the name
```

### to delete an item

Delete an item.

**Input Concepts**

| Concept | Description                         | Type                                         | Required | Default Value |
| ------- | ----------------------------------- | -------------------------------------------- | -------- | ------------- |
| `item`  | The item (file or folder) to delete | `s3 file reference` or `s3 folder reference` | Yes      | (no default)  |

**Examples**

Delete an item (file/folder) from AWS S3

```generic
create a json
use the above as the file
set the file's bucket_name to "bucket_name"
set the file's file_path to "test.txt"
delete an item with
    the item is the file
```

### to download a file

Get a file as a file object.

**Input Concepts**

| Concept                      | Description                                | Type                | Required | Default Value |
| ---------------------------- | ------------------------------------------ | ------------------- | -------- | ------------- |
| [`file`](#s3-file-reference) | The file reference to the file to download | `s3 file reference` | Yes      | (no default)  |

**Output Concepts**

| Concept  | Description              | Type   |
| -------- | ------------------------ | ------ |
| `answer` | the file as an IO object | `file` |

**Examples**

Download an item from AWS S3

```generic
create a json
use the above as the file
set the file's bucket_name to "bucket_name"
set the file's file_path to "test.txt"
download a file with
    the file is the file
```

### to get (buckets) from *s3*

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Get buckets from AWS S3.

**Output Concepts**

| Concept                 | Description             | Type        |
| ----------------------- | ----------------------- | ----------- |
| [`buckets`](#s3-bucket) | List of the aws buckets | `s3 bucket` |

**Examples**

Get the buckets list from AWS S3

```generic
get buckets from s3
```

### to get a (file) at a path

Get a reference to a file at a path.

**Input Concepts**

| Concept | Description          | Type   | Required | Default Value |
| ------- | -------------------- | ------ | -------- | ------------- |
| `path`  | The path to the file | `text` | Yes      | (no default)  |

**Output Concepts**

| Concept                      | Description      | Type                |
| ---------------------------- | ---------------- | ------------------- |
| [`file`](#s3-file-reference) | a file reference | `s3 file reference` |

**Examples**

Retrieve the file at a path

```generic
get a file at "bucket_name/abc/test.txt"
```

### to get a (folder) at a path

Get a reference to a folder at a path.

**Input Concepts**

| Concept | Description            | Type   | Required | Default Value |
| ------- | ---------------------- | ------ | -------- | ------------- |
| `path`  | The path to the folder | `text` | Yes      | (no default)  |

**Output Concepts**

| Concept                          | Description        | Type                  |
| -------------------------------- | ------------------ | --------------------- |
| [`folder`](#s3-folder-reference) | a folder reference | `s3 folder reference` |

**Examples**

Retrieve the folder at a path

```generic
get a folder at "bucket_name/abc/"
```

### to get a (root folder) from a bucket

Get a reference to the root folder in a bucket.

**Input Concepts**

| Concept                | Description            | Type        | Required | Default Value |
| ---------------------- | ---------------------- | ----------- | -------- | ------------- |
| [`bucket`](#s3-bucket) | The path to the folder | `s3 bucket` | Yes      | (no default)  |

**Output Concepts**

| Concept                               | Description        | Type                  |
| ------------------------------------- | ------------------ | --------------------- |
| [`root folder`](#s3-folder-reference) | a folder reference | `s3 folder reference` |

**Examples**

Retrieve the root folder of the AWS BUcket

```generic
get buckets from s3
use the above as the buckets
get a root folder from the first bucket's name
```

### to get some (folder's items)

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Get items from a folder.

**Input Concepts**

| Concept                          | Description                                       | Type                  | Required | Default Value |
| -------------------------------- | ------------------------------------------------- | --------------------- | -------- | ------------- |
| [`folder`](#s3-folder-reference) | The folder reference from which to list the items | `s3 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 | `s3 file reference` or `s3 folder reference` |

**Examples**

Get the list of the folder items from AWS S3

```generic
get a folder at "bucket_name/google"
use the above as the folder
get some folder's items with
    the folder is the folder
```

### to move an item to a folder

Update an item's location to a folder.

**Input Concepts**

| Concept                          | Description                                                                                                        | Type                                         | Required | Default Value |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | -------- | ------------- |
| `item`                           | The item (file or folder) to move                                                                                  | `s3 file reference` or `s3 folder reference` | Yes      | (no default)  |
| [`folder`](#s3-folder-reference) | The folder to move the item to                                                                                     | `s3 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 an item (file/folder) to another folder in AWS S3

```generic
create a json
use the above as the item
set the item's bucket_name to "bucket_name"
set the item's file_path to "kognitos-data.txt"
get a folder at "bucket_name/google"
use the above as the folder
move an item to folder with
    the item is the item
    the folder is the folder
```

### to rename an item to a name

Update an item's name.

**Input Concepts**

| Concept             | Description                                                                                                        | Type                                         | Required | Default Value |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | -------- | ------------- |
| `item`              | The item (file or folder) to rename                                                                                | `s3 file reference` or `s3 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 an item (file/folder) in AWS S3

```generic
create a json
use the above as the file
set the file's bucket_name to "bucket_name"
set the file's file_path to "test.txt"
rename an item to "test1.txt" with
    the item is the file
```

### to upload a (file) to a folder

Create a file in a folder.

**Input Concepts**

| Concept                          | Description                                                                                                        | Type                  | Required | Default Value |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------- | -------- | ------------- |
| `file`                           | The file to upload                                                                                                 | `file`                | Yes      | (no default)  |
| [`folder`](#s3-folder-reference) | The folder to upload the file to                                                                                   | `s3 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`](#s3-file-reference) | a file reference to the uploaded file | `s3 file reference` |

**Examples**

Upload a file to folder in AWS S3

```generic
the file
get a folder at "bucket_name/google"
use the above as the folder
the name is "new_test.txt"
upload the file to folder with
    the folder is the folder
    the file name is the name
```

## Concepts

### S3 file reference

Represents a reference to a file in an S3 bucket.

| Field Name    | Description                                                                         | Type     |
| ------------- | ----------------------------------------------------------------------------------- | -------- |
| `bucket_name` | The name of the S3 bucket containing the file.                                      | `text`   |
| `file_path`   | The full path of the file within the bucket, including the file name and extension. | `text`   |
| `parent_path` | The path of the parent folder of the file.                                          | `text`   |
| `name`        | The name of the file.                                                               | `text`   |
| `e_tag`       | The ETag of the file.                                                               | `text`   |
| `s3_uri`      | The S3 URI of the file.                                                             | `text`   |
| `size`        | The size of the file in bytes.                                                      | `number` |

### S3 folder reference

Represents a reference to a folder in an S3 bucket.

| Field Name    | Description                                                                                                 | Type     |
| ------------- | ----------------------------------------------------------------------------------------------------------- | -------- |
| `bucket_name` | The name of the S3 bucket containing the folder.                                                            | `text`   |
| `folder_path` | The path of the folder within the bucket. Should end with a trailing slash ('/') to indicate it's a folder. | `text`   |
| `parent_path` | The path of the parent folder of the folder.                                                                | `text`   |
| `name`        | The name of the folder.                                                                                     | `text`   |
| `e_tag`       | The ETag of the folder.                                                                                     | `text`   |
| `s3_uri`      | The S3 URI of the folder.                                                                                   | `text`   |
| `size`        | The size of the folder in bytes.                                                                            | `number` |

### S3 bucket

Represents a S3 bucket.

| Field Name | Description           | Type   |
| ---------- | --------------------- | ------ |
| `name`     | Name of the S3 Bucket | `text` |