From 8ebee82fde64d59364fdc305898255961e89fe18 Mon Sep 17 00:00:00 2001 From: Mathias Vandaele Date: Wed, 11 Dec 2024 09:25:15 +0100 Subject: [PATCH 1/2] docs(aws-s3): add documentation for the new aws s3 connector --- .../tasklist-api/tasklist-api-tutorial.md | 5 +- .../out-of-the-box-connectors/amazon-s3.md | 202 ++++++++++++++++++ .../tasklist-api/tasklist-api-tutorial.md | 5 +- .../tasklist-api/tasklist-api-tutorial.md | 5 +- .../tasklist-api/tasklist-api-tutorial.md | 5 +- .../tasklist-api/tasklist-api-tutorial.md | 5 +- 6 files changed, 217 insertions(+), 10 deletions(-) create mode 100644 docs/components/connectors/out-of-the-box-connectors/amazon-s3.md diff --git a/docs/apis-tools/tasklist-api/tasklist-api-tutorial.md b/docs/apis-tools/tasklist-api/tasklist-api-tutorial.md index 5ecdd5ba45..3dad8bb79c 100644 --- a/docs/apis-tools/tasklist-api/tasklist-api-tutorial.md +++ b/docs/apis-tools/tasklist-api/tasklist-api-tutorial.md @@ -250,8 +250,9 @@ export class TasklistModule implements OnModuleInit { logger.log("Tasklist credentials fetched"); axiosRef.defaults.baseURL = config.get("TASKLIST_API_ADDRESS"); - axiosRef.defaults.headers["Authorization"] = - `Bearer ${credentials.access_token}`; + axiosRef.defaults.headers[ + "Authorization" + ] = `Bearer ${credentials.access_token}`; axiosRef.defaults.headers["Content-Type"] = "application/json"; setTimeout(this.onModuleInit.bind(this), credentials.expires_in * 1000); // we need convert minutes to milliseconds } 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 new file mode 100644 index 0000000000..d665bd19f0 --- /dev/null +++ b/docs/components/connectors/out-of-the-box-connectors/amazon-s3.md @@ -0,0 +1,202 @@ +--- +id: amazon-s3 +sidebar_label: AWS S3 Connector +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 S3](https://aws.amazon.com/S3/) from your BPMN process. + +## Prerequisites + +To use the **Amazon S3 Connector**, you need to have an AWS account with an access key and secret key. + +The key needs those permissions: + +- GetObject +- DeleteObject +- PutObject + +Learn more about Amazon bedrock in +the [official S3 documentation](https://docs.aws.amazon.com/s3/). + +:::note +Use Camunda secrets to store credentials and avoid exposing sensitive information directly from the process. Refer +to [managing secrets](/components/console/manage-clusters/manage-secrets.md) to learn more. +::: + +## Create an Amazon Bedrock Connector task + +import ConnectorTask from '../../../components/react-components/connector-task.md' + + + +## Authentication + +Choose an applicable authentication type from the **Authentication** dropdown. Learn more about authentication types in +the related [appendix entry](#aws-authentication-types). + +There are two options to authenticate the Connector with AWS: + +- Choose **Credentials** in the **Authentication** dropdown if you have a valid pair of access and secret keys provided + by your AWS account administrator. This option is applicable for both SaaS and Self-Managed users. +- Choose **Default Credentials Chain (Hybrid/Self-Managed only)** in the **Authentication** dropdown if your system is + configured as an implicit authentication mechanism, such as role-based authentication, credentials supplied via + environment variables, or files on target host. This option is applicable only for Self-Managed or hybrid + distributions. This approach uses + the [Default Credential Provider Chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html) + to resolve required credentials. + +If you select **Credentials** to access the **Amazon Bedrock Connector**, the Connector requires the appropriate +credentials. The following authentication options are available: + +- **Access key**: Provide an access key of a user with permissions to the Amazon S3 actions +- **Secret key**: Provide the secret key of the user with the access key provided above. + +The **Access key** and the **Secret key** are required properties and must be provided to use the Connector. + +## Region + +In the **Region** field write the region of the deployed endpoint. + +## Action + +There are three possible actions with the Amazon S3 Connector: `Upload Document`, `Download Document` and +`Delete Document`. + +### Upload Document + +This action is meant to upload the document. The incoming document must come as a reference from previous process. + +#### Parameters + +| Parameter | Description | +| :----------- | :----------------------------------------------------------------------------------------------------------------------- | +| `AWS bucket` | Specify the targeted AWS S3 bucket where the document should be uploaded. | +| `AWS key` | Specify the key of the document which uniquely identifies the object in an Amazon S3 bucket. | +| `Document` | Specify the document which should be uploaded to S3. should be provided as a feel expression with the document reference | + +:::info +To learn more about Friendly Enough Expression Language (FEEL) expression, +see [what is FEEL?](/components/modeler/feel/what-is-feel.md). +::: + +#### Response Structure + +Upon successfully uploading the document, the following JSON response is returned: + +- `bucket`: Echoes back the bucket of the uploaded document. +- `key`: Echoes back the unique key of the uploaded document. +- `link`: The link + +#### Example Response + +The following is an example of a successful send upload operation: + +```json +{ + "bucket": "Example Subject", + "key": true, + "link": "https://mybucket.s3.amazonaws.com/test" +} +``` + +### Download Document + +This action is meant to download the document from AWS S3. + +#### Parameters + +| Parameter | Description | +| :---------------- | :------------------------------------------------------------------------------------------------------------------------ | +| `AWS bucket` | Specify the targeted AWS S3 bucket where the document should be downloaded from. | +| `AWS key` | Specify the key of the document which uniquely identifies the object in an Amazon S3 bucket. | +| `Create document` | `false` or `true`, if false no document will be created and the output will be inserted as json, text or base64 raw bytes | + +:::info +To learn more about Friendly Enough Expression Language (FEEL) expression, +see [what is FEEL?](/components/modeler/feel/what-is-feel.md). +::: + +#### Response Structure + +Upon successfully download operation, the following JSON response is returned: + +- `bucket`: Echoes back the bucket of the uploaded document. +- `key`: Echoes back the unique key of the uploaded document. +- `document`: The document. This will always be null is `Create document` is set to false, as no document reference will + be created +- `content`: The content inside the downloaded document, It will be shown as JSON, text or base64 raw bytes depending on + the content-type. + +#### Example Response + +The following is an example of a successful download operation: + +```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" + }, + "documentType": "camunda" + }, + "content": null +} +``` + +or + +```json +{ + "bucket": "Example Subject", + "key": true, + "document": null, + "content": { + "json": { + "testKey": "testValue" + } + } +} +``` + +### Delete Document + +This action is meant to delete the document from AWS S3. + +#### Parameters + +| Parameter | Description | +| :----------- | :------------------------------------------------------------------------------------------- | +| `AWS bucket` | Specify the targeted AWS S3 bucket where the document should be deleted from. | +| `AWS key` | Specify the key of the document which uniquely identifies the object in an Amazon S3 bucket. | + +:::info +To learn more about Friendly Enough Expression Language (FEEL) expression, +see [what is FEEL?](/components/modeler/feel/what-is-feel.md). +::: + +#### Response Structure + +Upon successfully deleting the document, the following JSON response is returned: + +- `bucket`: Echoes back the bucket of the uploaded document. +- `key`: Echoes back the unique key of the uploaded document. + +#### Example Response + +The following is an example of a successful delete operation: + +```json +{ + "bucket": "Example Subject", + "key": "document.txt" +} +``` diff --git a/versioned_docs/version-8.3/apis-tools/tasklist-api/tasklist-api-tutorial.md b/versioned_docs/version-8.3/apis-tools/tasklist-api/tasklist-api-tutorial.md index d78fc5907d..21c5449ffc 100644 --- a/versioned_docs/version-8.3/apis-tools/tasklist-api/tasklist-api-tutorial.md +++ b/versioned_docs/version-8.3/apis-tools/tasklist-api/tasklist-api-tutorial.md @@ -250,8 +250,9 @@ export class TasklistModule implements OnModuleInit { logger.log("Tasklist credentials fetched"); axiosRef.defaults.baseURL = config.get("TASKLIST_API_ADDRESS"); - axiosRef.defaults.headers["Authorization"] = - `Bearer ${credentials.access_token}`; + axiosRef.defaults.headers[ + "Authorization" + ] = `Bearer ${credentials.access_token}`; axiosRef.defaults.headers["Content-Type"] = "application/json"; setTimeout(this.onModuleInit.bind(this), credentials.expires_in * 1000); // we need convert minutes to milliseconds } diff --git a/versioned_docs/version-8.4/apis-tools/tasklist-api/tasklist-api-tutorial.md b/versioned_docs/version-8.4/apis-tools/tasklist-api/tasklist-api-tutorial.md index 5ecdd5ba45..3dad8bb79c 100644 --- a/versioned_docs/version-8.4/apis-tools/tasklist-api/tasklist-api-tutorial.md +++ b/versioned_docs/version-8.4/apis-tools/tasklist-api/tasklist-api-tutorial.md @@ -250,8 +250,9 @@ export class TasklistModule implements OnModuleInit { logger.log("Tasklist credentials fetched"); axiosRef.defaults.baseURL = config.get("TASKLIST_API_ADDRESS"); - axiosRef.defaults.headers["Authorization"] = - `Bearer ${credentials.access_token}`; + axiosRef.defaults.headers[ + "Authorization" + ] = `Bearer ${credentials.access_token}`; axiosRef.defaults.headers["Content-Type"] = "application/json"; setTimeout(this.onModuleInit.bind(this), credentials.expires_in * 1000); // we need convert minutes to milliseconds } diff --git a/versioned_docs/version-8.5/apis-tools/tasklist-api/tasklist-api-tutorial.md b/versioned_docs/version-8.5/apis-tools/tasklist-api/tasklist-api-tutorial.md index 5ecdd5ba45..3dad8bb79c 100644 --- a/versioned_docs/version-8.5/apis-tools/tasklist-api/tasklist-api-tutorial.md +++ b/versioned_docs/version-8.5/apis-tools/tasklist-api/tasklist-api-tutorial.md @@ -250,8 +250,9 @@ export class TasklistModule implements OnModuleInit { logger.log("Tasklist credentials fetched"); axiosRef.defaults.baseURL = config.get("TASKLIST_API_ADDRESS"); - axiosRef.defaults.headers["Authorization"] = - `Bearer ${credentials.access_token}`; + axiosRef.defaults.headers[ + "Authorization" + ] = `Bearer ${credentials.access_token}`; axiosRef.defaults.headers["Content-Type"] = "application/json"; setTimeout(this.onModuleInit.bind(this), credentials.expires_in * 1000); // we need convert minutes to milliseconds } diff --git a/versioned_docs/version-8.6/apis-tools/tasklist-api/tasklist-api-tutorial.md b/versioned_docs/version-8.6/apis-tools/tasklist-api/tasklist-api-tutorial.md index 5ecdd5ba45..3dad8bb79c 100644 --- a/versioned_docs/version-8.6/apis-tools/tasklist-api/tasklist-api-tutorial.md +++ b/versioned_docs/version-8.6/apis-tools/tasklist-api/tasklist-api-tutorial.md @@ -250,8 +250,9 @@ export class TasklistModule implements OnModuleInit { logger.log("Tasklist credentials fetched"); axiosRef.defaults.baseURL = config.get("TASKLIST_API_ADDRESS"); - axiosRef.defaults.headers["Authorization"] = - `Bearer ${credentials.access_token}`; + axiosRef.defaults.headers[ + "Authorization" + ] = `Bearer ${credentials.access_token}`; axiosRef.defaults.headers["Content-Type"] = "application/json"; setTimeout(this.onModuleInit.bind(this), credentials.expires_in * 1000); // we need convert minutes to milliseconds } From 673d510ba4d67de80d42cf2fd5e860be8947bc34 Mon Sep 17 00:00:00 2001 From: mesellings Date: Thu, 12 Dec 2024 09:50:45 +0000 Subject: [PATCH 2/2] TW edits --- .../out-of-the-box-connectors/amazon-s3.md | 106 +++++++++--------- sidebars.js | 1 + 2 files changed, 53 insertions(+), 54 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 index d665bd19f0..0a7691b2e8 100644 --- 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,25 +5,22 @@ 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 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 -To use the **Amazon S3 Connector**, you need to have an AWS account with an access key and secret key. +To use the **Amazon S3 Connector**, you will need an AWS account with an access key and secret key. -The key needs those permissions: +The key will need the following permissions: -- GetObject -- DeleteObject -- PutObject +- `GetObject` +- `DeleteObject` +- `PutObject` -Learn more about Amazon bedrock in -the [official S3 documentation](https://docs.aws.amazon.com/s3/). +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 directly from the process. Refer -to [managing secrets](/components/console/manage-clusters/manage-secrets.md) to learn more. +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 @@ -34,65 +31,67 @@ import ConnectorTask from '../../../components/react-components/connector-task.m ## Authentication -Choose an applicable authentication type from the **Authentication** dropdown. Learn more about authentication types in -the related [appendix entry](#aws-authentication-types). +Select an authentication type from the **Authentication** dropdown. -There are two options to authenticate the Connector with AWS: +- **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. -- Choose **Credentials** in the **Authentication** dropdown if you have a valid pair of access and secret keys provided - by your AWS account administrator. This option is applicable for both SaaS and Self-Managed users. -- Choose **Default Credentials Chain (Hybrid/Self-Managed only)** in the **Authentication** dropdown if your system is +- **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 - environment variables, or files on target host. This option is applicable only for Self-Managed or hybrid + environment variables, or files on target host. This option is only supported for Self-Managed or hybrid distributions. This approach uses the [Default Credential Provider Chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html) to resolve required credentials. -If you select **Credentials** to access the **Amazon Bedrock Connector**, the Connector requires the appropriate -credentials. The following authentication options are available: +If you select **Credentials**, you must supply the appropriate +credentials: -- **Access key**: Provide an access key of a user with permissions to the Amazon S3 actions +- **Access key**: Provide an access key of a user with permissions to the Amazon S3 actions. - **Secret key**: Provide the secret key of the user with the access key provided above. +:::note The **Access key** and the **Secret key** are required properties and must be provided to use the Connector. +::: ## Region -In the **Region** field write the region of the deployed endpoint. +In the **Region** field, enter the region of the deployed endpoint. ## Action -There are three possible actions with the Amazon S3 Connector: `Upload Document`, `Download Document` and -`Delete Document`. +The Amazon S3 Connector supports the following actions: + +- `Upload Document` +- `Download Document` +- `Delete Document` ### Upload Document -This action is meant to upload the document. The incoming document must come as a reference from previous process. +Upload a document. The incoming document must be a reference from the previous process. #### Parameters -| Parameter | Description | -| :----------- | :----------------------------------------------------------------------------------------------------------------------- | -| `AWS bucket` | Specify the targeted AWS S3 bucket where the document should be uploaded. | -| `AWS key` | Specify the key of the document which uniquely identifies the object in an Amazon S3 bucket. | -| `Document` | Specify the document which should be uploaded to S3. should be 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` | 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. | :::info -To learn more about Friendly Enough Expression Language (FEEL) expression, +To learn more about Friendly Enough Expression Language (FEEL) expressions, see [what is FEEL?](/components/modeler/feel/what-is-feel.md). ::: #### Response Structure -Upon successfully uploading the document, the following JSON response is returned: +The following JSON response is returned after a successful document upload operation: - `bucket`: Echoes back the bucket of the uploaded document. - `key`: Echoes back the unique key of the uploaded document. -- `link`: The link +- `link`: The document link. #### Example Response -The following is an example of a successful send upload operation: +The following example shows a successful send upload operation response: ```json { @@ -104,35 +103,34 @@ The following is an example of a successful send upload operation: ### Download Document -This action is meant to download the document from AWS S3. +Download the document from AWS S3. #### Parameters -| Parameter | Description | -| :---------------- | :------------------------------------------------------------------------------------------------------------------------ | -| `AWS bucket` | Specify the targeted AWS S3 bucket where the document should be downloaded from. | -| `AWS key` | Specify the key of the document which uniquely identifies the object in an Amazon S3 bucket. | -| `Create document` | `false` or `true`, if false no document will be created and the output will be inserted as json, text or base64 raw bytes | +| 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. | :::info -To learn more about Friendly Enough Expression Language (FEEL) expression, +To learn more about Friendly Enough Expression Language (FEEL) expressions, see [what is FEEL?](/components/modeler/feel/what-is-feel.md). ::: #### Response Structure -Upon successfully download operation, the following JSON response is returned: +The following JSON response is returned after a successful document download operation: - `bucket`: Echoes back the bucket of the uploaded document. - `key`: Echoes back the unique key of the uploaded document. -- `document`: The document. This will always be null is `Create document` is set to false, as no document reference will - be created -- `content`: The content inside the downloaded document, It will be shown as JSON, text or base64 raw bytes depending on +- `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. #### Example Response -The following is an example of a successful download operation: +The following examples show a successful download operation response: ```json { @@ -169,30 +167,30 @@ or ### Delete Document -This action is meant to delete the document from AWS S3. +Delete the document from AWS S3. #### Parameters -| Parameter | Description | -| :----------- | :------------------------------------------------------------------------------------------- | -| `AWS bucket` | Specify the targeted AWS S3 bucket where the document should be deleted from. | -| `AWS key` | Specify the key of the document which uniquely identifies the object in an Amazon S3 bucket. | +| 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. | :::info -To learn more about Friendly Enough Expression Language (FEEL) expression, +To learn more about Friendly Enough Expression Language (FEEL) expressions, see [what is FEEL?](/components/modeler/feel/what-is-feel.md). ::: #### Response Structure -Upon successfully deleting the document, the following JSON response is returned: +The following JSON response is returned after a successful document deletion operation: - `bucket`: Echoes back the bucket of the uploaded document. - `key`: Echoes back the unique key of the uploaded document. #### Example Response -The following is an example of a successful delete operation: +The following example shows a successful deletion operation response: ```json { diff --git a/sidebars.js b/sidebars.js index 14ac338fc9..c374e35c50 100644 --- a/sidebars.js +++ b/sidebars.js @@ -326,6 +326,7 @@ module.exports = { "components/connectors/out-of-the-box-connectors/amazon-sagemaker", "components/connectors/out-of-the-box-connectors/amazon-sns", "components/connectors/out-of-the-box-connectors/amazon-sqs", + "components/connectors/out-of-the-box-connectors/amazon-s3", "components/connectors/out-of-the-box-connectors/amazon-textract", ], },