docs(aws-s3): add documentation for the new aws s3 connector 2

camunda · Dec 20, 2024 · 1e33c4c · 1e33c4c
1 parent 9ead989
commit 1e33c4c
Showing 1 changed file with 42 additions and 35 deletions.
diff --git a/docs/components/connectors/out-of-the-box-connectors/amazon-s3.md b/docs/components/connectors/out-of-the-box-connectors/amazon-s3.md
@@ -5,7 +5,8 @@ title: Amazon S3 Connector
 description: Interact with Amazon S3 services from your BPMN process.
 ---
 
-The **Amazon S3 Connector** is an outbound Connector that allows you to interact with [Amazon Simple Storage Service (Amazon S3)](https://aws.amazon.com/S3/) from your BPMN process.
+The **Amazon S3 Connector** is an outbound Connector that allows you to interact
+with [Amazon Simple Storage Service (Amazon S3)](https://aws.amazon.com/S3/) from your BPMN process.
 
 ## Prerequisites
 
@@ -20,7 +21,8 @@ The key will need the following permissions:
 Learn more about Amazon S3 in the [Amazon Simple Storage Service Documentation](https://docs.aws.amazon.com/s3/).
 
 :::note
-Use Camunda secrets to store credentials and avoid exposing sensitive information from the process. See [managing secrets](/components/console/manage-clusters/manage-secrets.md).
+Use Camunda secrets to store credentials and avoid exposing sensitive information from the process.
+See [managing secrets](/components/console/manage-clusters/manage-secrets.md).
 :::
 
 ## Create an Amazon Bedrock Connector task
@@ -33,7 +35,8 @@ import ConnectorTask from '../../../components/react-components/connector-task.m
 
 Select an authentication type from the **Authentication** dropdown.
 
-- **Credentials** (SaaS/Self-Managed): Select this option if you have a valid pair of access and secret keys provided by your AWS account administrator. This option is supported for both SaaS and Self-Managed users.
+- **Credentials** (SaaS/Self-Managed): Select this option if you have a valid pair of access and secret keys provided by
+  your AWS account administrator. This option is supported for both SaaS and Self-Managed users.
 
 - **Default Credentials Chain** (Hybrid/Self-Managed only): Select this option if your system is
   configured as an implicit authentication mechanism, such as role-based authentication, credentials supplied via
@@ -70,11 +73,11 @@ Upload a document. The incoming document must be a reference from the previous p
 
 #### Parameters
 
-| Parameter    | Description                                                                                            |
-| :----------- | :----------------------------------------------------------------------------------------------------- |
-| `AWS bucket` | The targeted AWS S3 bucket where the document should be uploaded.                                      |
-| `AWS key`    | The key of the document that uniquely identifies the object in an Amazon S3 bucket.                    |
-| `Document`   | The document that should be uploaded to S3, provided as a FEEL expression with the document reference. |
+| Parameter    | Description                                                                                                                                      |
+|:-------------|:-------------------------------------------------------------------------------------------------------------------------------------------------|
+| `AWS bucket` | The targeted AWS S3 bucket where the document should be uploaded.                                                                                |
+| `AWS key`    | (Optional) The key of the document that uniquely identifies the object in an Amazon S3 bucket. Will fallback to the document filename if not set |
+| `Document`   | The document that should be uploaded to S3, provided as a FEEL expression with the document reference.                                           |
 
 :::info
 To learn more about Friendly Enough Expression Language (FEEL) expressions,
@@ -95,9 +98,9 @@ The following example shows a successful send upload operation response:
 
 ```json
 {
-  "bucket": "Example Subject",
-  "key": true,
-  "link": "https://mybucket.s3.amazonaws.com/test"
+  "bucket":"Example Subject",
+  "key":true,
+  "link":"https://mybucket.s3.amazonaws.com/test"
 }
 ```
 
@@ -108,7 +111,7 @@ Download the document from AWS S3.
 #### Parameters
 
 | Parameter         | Description                                                                                                                 |
-| :---------------- | :-------------------------------------------------------------------------------------------------------------------------- |
+|:------------------|:----------------------------------------------------------------------------------------------------------------------------|
 | `AWS bucket`      | The targeted AWS S3 bucket that the document should be downloaded from.                                                     |
 | `AWS key`         | The key of the document that uniquely identifies the object in an Amazon S3 bucket.                                         |
 | `Create document` | Either `false` or `true`. If `false`, no document is created and the output is inserted as JSON, text, or base64 raw bytes. |
@@ -124,42 +127,46 @@ The following JSON response is returned after a successful document download ope
 
 - `bucket`: Echoes back the bucket of the uploaded document.
 - `key`: Echoes back the unique key of the uploaded document.
-- `document`: The document. This is always null if `Create document` is set to `false`, as no document reference is created.
-- `content`: The content of the downloaded document, shown as JSON, text, or base64 raw bytes depending on
-  the content-type.
+- `element`: Represents the document in the workflow. The behavior changes based on the `Create document` setting:
+    - If `Create document` is set to `false`:
+        - For `String` content type: `element` will contain the string content of the document.
+        - For `Json` content type: `element` will contain the JSON content of the document.
+        - For other content types: `element` will contain the raw bytes of the document, encoded in base64.
+    - If `Create document` is set to `true`:
+        - `element` will contain a document reference, rather than the document content itself.
 
 #### Example Response
 
 The following examples show a successful download operation response:
 
 ```json
 {
-  "bucket": "Example Subject",
-  "key": true,
-  "document": {
-    "storeId": "in-memory",
-    "documentId": "20f1fd6a-d8ea-403b-813c-e281c1193495",
-    "metadata": {
-      "contentType": "image/webp; name=305a4816-b3df-4724-acd3-010478a54add.webp",
-      "size": 311032,
-      "fileName": "305a4816-b3df-4724-acd3-010478a54add.webp"
+  "bucket":"Example Subject",
+  "key":true,
+  "document":{
+    "storeId":"in-memory",
+    "documentId":"20f1fd6a-d8ea-403b-813c-e281c1193495",
+    "metadata":{
+      "contentType":"image/webp; name=305a4816-b3df-4724-acd3-010478a54add.webp",
+      "size":311032,
+      "fileName":"305a4816-b3df-4724-acd3-010478a54add.webp"
     },
-    "documentType": "camunda"
+    "camunda.document.type":"camunda"
   },
-  "content": null
+  "content":null
 }
 ```
 
 or
 
 ```json
 {
-  "bucket": "Example Subject",
-  "key": true,
-  "document": null,
-  "content": {
-    "json": {
-      "testKey": "testValue"
+  "bucket":"Example Subject",
+  "key":true,
+  "document":null,
+  "content":{
+    "json":{
+      "testKey":"testValue"
     }
   }
 }
@@ -172,7 +179,7 @@ Delete the document from AWS S3.
 #### Parameters
 
 | Parameter    | Description                                                                         |
-| :----------- | :---------------------------------------------------------------------------------- |
+|:-------------|:------------------------------------------------------------------------------------|
 | `AWS bucket` | The targeted AWS S3 bucket that the document should be deleted from.                |
 | `AWS key`    | The key of the document that uniquely identifies the object in an Amazon S3 bucket. |
 
@@ -194,7 +201,7 @@ The following example shows a successful deletion operation response:
 
 ```json
 {
-  "bucket": "Example Subject",
-  "key": "document.txt"
+  "bucket":"Example Subject",
+  "key":"document.txt"
 }
 ```