From beee1e29e4fe1ea14b3590dd8aa2b1da33de1d05 Mon Sep 17 00:00:00 2001 From: DenovVasil Date: Thu, 3 Oct 2024 14:18:15 +0300 Subject: [PATCH 1/5] docs: add comprehend doc --- .../amazon-comprehend.md | 195 ++++++++++++++++++ .../available-connectors-overview.md | 1 + optimize_sidebars.js | 4 + sidebars.js | 1 + 4 files changed, 201 insertions(+) create mode 100644 docs/components/connectors/out-of-the-box-connectors/amazon-comprehend.md diff --git a/docs/components/connectors/out-of-the-box-connectors/amazon-comprehend.md b/docs/components/connectors/out-of-the-box-connectors/amazon-comprehend.md new file mode 100644 index 0000000000..407b8fca1a --- /dev/null +++ b/docs/components/connectors/out-of-the-box-connectors/amazon-comprehend.md @@ -0,0 +1,195 @@ +--- +id: amazon-comprehend +title: Amazon Comprehend Connector +sidebar_label: AWS Comprehend Connector +description: Comprehend uses natural language processing (NLP) to extract insights about the content of documents. +--- + +:::info +The **Amazon Comprehend Connector** is available for `8.6.0` or later. +::: + +The **Amazon Comprehend Connector** allows you to integrate your BPMN service with [Amazon Comprehend Service](https://docs.aws.amazon.com/comprehend/latest/dg/what-is.html) to extract insights about the content of documents.. + +## Prerequisites + +To use the **Amazon Comprehend Connector**, you need to have an **AWS IAM Access Key** and **Secret Key** with the appropriate Comprehend permissions. Refer to the [AWS Comprehend Setting Up](https://docs.aws.amazon.com/comprehend/latest/dg/setting-up.html) for setup instructions. + +:::note +Use **Camunda secrets** to avoid exposing your AWS IAM credentials as plain text. +Refer to [managing secrets](components/console/manage-clusters/manage-secrets.md) for more details. +::: + +## Create an Amazon Comprehend Connector task + +import ConnectorTask from '../../../components/react-components/connector-task.md' + + + +## To make your Amazon Comprehend Connector executable + +To execute the **Amazon Comprehend Connector**, ensure all mandatory fields are correctly filled. + +## 1. Authentication + +Choose an authentication type from the **Authentication** dropdown. For details on the different authentication types, refer to the [Appendix](#aws-authentication-types). + +If you select **Credentials**, the following fields must be provided: + +- **Access Key**: The AWS access key for a user with Comprehend permissions. +- **Secret Key**: The corresponding AWS secret key. + +Both **Access Key** and **Secret Key** are required to use the connector. + +## 2. **Configuration (AWS Region)** + +After authentication, set the AWS **Region** where the Textract service is hosted: + +- **Region**: Specify the region (e.g., `us-east-1`, `eu-west-1`). + +> **Note**: Ensure the region matches the location of your Comprehend service and S3 buckets to reduce latency and meet compliance requirements. +> For a full list of AWS regions, refer to [AWS Regional Data](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/). + +## 3. Configure Input + +### Execution Types + +Select the desired execution type from the **Execution Type** dropdown. The following options are available: + +- **Sync** + +Use **Sync** execution for creates a classification request to analyze a single document in real-time. + +For more details, refer to [sync execution](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ClassifyDocument.html). + +- **Async** + +Use **Async** execution to starts an asynchronous document classification job using a custom classification model. This method allows you to submit a document for analysis and receive results at a later time, making it ideal for background processing or batch operations. + +**Async** execution enables you to process documents without waiting for immediate responses. This is particularly useful for larger files or when handling multiple documents simultaneously. + +For more details on the fields that can be configured during asynchronous execution, refer to [async execution](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartDocumentClassificationJob.html). + +### Sync execution fields: + +- **Text (mandatory)** The document text to be analyzed. +- **Document read action** This field defines the Amazon Textract API operation that Amazon Comprehend uses to extract text from PDF files and image files. For more details, refer to [Document read action](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadAction). +- **Document read mode** Determines the text extraction actions for PDF files. For more details, refer to [Document read mode](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadMode). +- **Analyze tables** Returns additional information about any tables that are detected in the input document. For more details, refer to [Feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). +- **Analyze forms** Returns additional information about any forms that are detected in the input document. For more details, refer to [Feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). +- **Endpoint Arn (mandatory)** The Amazon Resource Number (ARN) of the endpoint. For more details, refer to [Classify Document](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ClassifyDocument.html#API_ClassifyDocument_RequestSyntax). + +### Async execution fields: + +- **Document read action** This field defines the Amazon Textract API operation that Amazon Comprehend uses to extract text from PDF files and image files. For more details, refer to [Document read action](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadAction). +- **Document read mode** Determines the text extraction actions for PDF files. For more details, refer to [Document read mode](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadMode). +- **Analyze tables** Returns additional information about any tables that are detected in the input document. For more details, refer to [Feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). +- **Analyze forms** Returns additional information about any forms that are detected in the input document. For more details, refer to [Feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). +- **Input S3 URI (mandatory)** The Amazon S3 URI for the input data. For more details, refer to [S3 URI](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_InputDataConfig.html#comprehend-Type-InputDataConfig-S3Uri). +- **Input Format** Specifies how the text in an input file should be processed. For more details, refer to [InputFormat](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_InputDataConfig.html#comprehend-Type-InputDataConfig-InputFormat). +- **Client request token** A unique identifier for the request. If you do not set the client request token, Amazon Comprehend generates one. +- **Data access role ARN (mandatory)** The Amazon Resource Name (ARN) of the IAM role that grants Amazon Comprehend read access to your input data. +- **Document classifier ARN** The Amazon Resource Name (ARN) of the document classifier to use to process the job. +- **Flywheel ARN** The Amazon Resource Number (ARN) of the flywheel associated with the model to use. +- **Job name** The identifier of the job. +- **Output S3 URI (mandatory)** The Amazon S3 location where you want to write the output data. For more details, refer to [Output data config](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_OutputDataConfig.html). +- **Output Kms Key Id** The id for the AWS Key Management Service (KMS) key that Amazon Comprehend uses to encrypt the output results from an analysis job. For more details, refer to [Output data config](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_OutputDataConfig.html). +- **Tags** Tags to associate with the document classification job. A tag is a key-value pair that adds metadata to a resource used by Amazon Comprehend. + **Example:** + +```feel += {"status": "active"} +``` + +- **Volume Kms Key Id** ID for the AWS Key Management Service (KMS) key that Amazon Comprehend uses to encrypt data on the storage volume attached to the ML compute instance(s) that process the analysis job. +- **Security group ids** The ID number for a security group on an instance of your private VPC. For more details, refer to [Security group](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_VpcConfig.html#comprehend-Type-VpcConfig-SecurityGroupIds). **Example:** + +```feel += ["sg-07a2cc6d96e4ec178"] +``` + +- **Subnets** The ID for each subnet being used in your private VPC. For more details, refer to [Subnets](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_VpcConfig.html#comprehend-Type-VpcConfig-Subnets). + **Example:** + +```feel += ["subnet-013eac53274e1d93f"] +``` + +:::note +To use **VPC** you need at last one vpc endpoint For more details, refer to [Create a VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint-aws). +::: + +## Amazon Comprehend Connector Response + +The response from the **Amazon Comprehend Connector** will mirror the AWS Comprehend service’s response. The type of response you receive depends on the execution mode selected: + +- **[Sync Response](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ClassifyDocument.html#API_ClassifyDocument_ResponseSyntax)**: Provides immediate analysis for provided text. +- **[Asynchronous Response](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartDocumentClassificationJob.html#API_StartDocumentClassificationJob_ResponseSyntax)**: Used for batch processing where results are returned later through job completion. + +### Using the Comprehend Connector Response in Your Process + +The **Amazon Comprehend Connector** provides the same response structure as the AWS Comprehend API. You can map fields from the response to process variables, depending on your needs. Here's an example of how to extract specific fields using **Result Expression** and **Result Variable**. + +### Example Comprehend Response (Real-time Execution) + +Utilize output mapping to align this response with process variables: + +1. Use **Result Variable** to store the response in a process variable. For example, `myResultVariable`. This approach stores the entire Comprehend message as a process variable named `myResultVariable`. +2. Use **Result Expression** to map fields from the response into process variables. This approach allows for more granularity. Instead of storing the entire response in one variable, you can extract specific fields from the **Comprehend Connector** message and assign them to different process variables. This is particularly useful when you are only interested in certain parts of the message, or when different parts of the message need to be used separately in your process. + Example: + +```json +{ + "classes": [ + { + "name": "CHECKING_AC", + "score": 0.5423, + "page": null + }, + { + "name": "SAVINGS_AC", + "score": 0.4577, + "page": null + } + ], + "labels": null, + "documentMetadata": null, + "documentType": null, + "errors": null, + "warnings": null +} +``` + +#### Mapping Example + +To store only first **Classes** element information, use the following result **expression**: + +```feel += {classInfo: classes[1]} +``` + +Mapped values **result**: + +```json +{ + "name": "CHECKING_AC", + "score": 0.5422999858856201, + "page": null +} +``` + +## Appendix & FAQ + +### How do I securely store AWS IAM credentials for my Comprehend Connector? + +Store your AWS IAM credentials as **Camunda Secrets** to avoid exposing sensitive information. Follow our [Managing Secrets Guide](components/console/manage-clusters/manage-secrets.md) to learn more. + +### AWS Authentication Types + +You can authenticate the **Amazon Comprehend Connector** in two ways: + +1. **Credentials**: + Select this option if you have an AWS **Access Key** and **Secret Key**. This method is applicable for both SaaS and Self-Managed users. + +2. **Default Credentials Chain (Hybrid/Self-Managed only)**: + Select this option if your system uses implicit authentication methods like role-based access, environment variables, or files on the target host. This method is applicable only for Self-Managed or Hybrid environments. It uses the [Default Credential Provider Chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html) to resolve credentials. diff --git a/docs/components/connectors/out-of-the-box-connectors/available-connectors-overview.md b/docs/components/connectors/out-of-the-box-connectors/available-connectors-overview.md index 4f4294bd87..5ddfe34054 100644 --- a/docs/components/connectors/out-of-the-box-connectors/available-connectors-overview.md +++ b/docs/components/connectors/out-of-the-box-connectors/available-connectors-overview.md @@ -33,6 +33,7 @@ import TabItem from "@theme/TabItem"; - [Amazon SNS Outbound Connector](/components/connectors/out-of-the-box-connectors/amazon-sns.md) - Send messages to [Amazon Simple Notification Service](https://aws.amazon.com/sns/) from your BPMN process. - [Amazon SQS Connector](/components/connectors/out-of-the-box-connectors/amazon-sqs.md) - Send messages to [Amazon Simple Queue Service](https://aws.amazon.com/sqs/) from your BPMN process. - [Amazon Textract Connector](components/connectors/out-of-the-box-connectors/amazon-textract.md) - Interact with the [Amazon Textract Service](https://aws.amazon.com/textract/) from your BPMN process. +- [Amazon Comprehend Connector](/components/connectors/out-of-the-box-connectors/amazon-comprehend.md) - Interact with the [Amazon Comprehend service](https://aws.amazon.com/comprehend/) from your BPMN process. - [Asana Connector](/components/connectors/out-of-the-box-connectors/asana.md) - Manage [Asana](https://asana.com/) projects and tasks from your BPMN process. - [Automation Anywhere Connector](/components/connectors/out-of-the-box-connectors/automation-anywhere.md) - Orchestrate your [Automation Anywhere](https://www.automationanywhere.com/) queue from your BPMN process. - [AWS Lambda Connector](/components/connectors/out-of-the-box-connectors/aws-lambda.md) - Invoke [AWS Lambda Functions](https://aws.amazon.com/lambda/) from your BPMN process. diff --git a/optimize_sidebars.js b/optimize_sidebars.js index e8683beb92..8777cb245a 100644 --- a/optimize_sidebars.js +++ b/optimize_sidebars.js @@ -922,6 +922,10 @@ module.exports = { "AWS SQS Connector", "components/connectors/out-of-the-box-connectors/amazon-sqs/" ), + docsLink( + "AWS Comprehend Connector", + "/components/connectors/out-of-the-box-connectors/amazon-comprehend/" + ), docsLink( "AWS Textract Connector", "components/connectors/out-of-the-box-connectors/amazon-textract/" diff --git a/sidebars.js b/sidebars.js index 2dfafa6cf9..2dfe148d71 100644 --- a/sidebars.js +++ b/sidebars.js @@ -327,6 +327,7 @@ module.exports = { "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-textract", + "components/connectors/out-of-the-box-connectors/amazon-comprehend", ], }, "components/connectors/out-of-the-box-connectors/blueprism", From 535fcd5360a78785be8b4aef9f9452758919b8e5 Mon Sep 17 00:00:00 2001 From: Christina Ausley Date: Mon, 7 Oct 2024 12:35:24 -0400 Subject: [PATCH 2/5] technical review --- .../amazon-comprehend.md | 107 +++++++++--------- .../available-connectors-overview.md | 2 +- optimize_sidebars.js | 8 +- sidebars.js | 1 + 4 files changed, 59 insertions(+), 59 deletions(-) diff --git a/docs/components/connectors/out-of-the-box-connectors/amazon-comprehend.md b/docs/components/connectors/out-of-the-box-connectors/amazon-comprehend.md index 407b8fca1a..664fd950d4 100644 --- a/docs/components/connectors/out-of-the-box-connectors/amazon-comprehend.md +++ b/docs/components/connectors/out-of-the-box-connectors/amazon-comprehend.md @@ -2,18 +2,18 @@ id: amazon-comprehend title: Amazon Comprehend Connector sidebar_label: AWS Comprehend Connector -description: Comprehend uses natural language processing (NLP) to extract insights about the content of documents. +description: Use the Amazon Comprehend Connector to extract insights from the content of your documents, like key phrases and personal identifiable information. --- :::info The **Amazon Comprehend Connector** is available for `8.6.0` or later. ::: -The **Amazon Comprehend Connector** allows you to integrate your BPMN service with [Amazon Comprehend Service](https://docs.aws.amazon.com/comprehend/latest/dg/what-is.html) to extract insights about the content of documents.. +The **Amazon Comprehend Connector** allows you to integrate your BPMN service with [Amazon Comprehend](https://docs.aws.amazon.com/comprehend/latest/dg/what-is.html), a service which extracts insights about the content of documents, such as personal identifiable information and key phrases. ## Prerequisites -To use the **Amazon Comprehend Connector**, you need to have an **AWS IAM Access Key** and **Secret Key** with the appropriate Comprehend permissions. Refer to the [AWS Comprehend Setting Up](https://docs.aws.amazon.com/comprehend/latest/dg/setting-up.html) for setup instructions. +To use the **Amazon Comprehend Connector**, you must have an **AWS IAM Access Key** and **Secret Key** with the appropriate Comprehend permissions. Refer to the [AWS Comprehend set up instructions](https://docs.aws.amazon.com/comprehend/latest/dg/setting-up.html). :::note Use **Camunda secrets** to avoid exposing your AWS IAM credentials as plain text. @@ -26,89 +26,91 @@ import ConnectorTask from '../../../components/react-components/connector-task.m -## To make your Amazon Comprehend Connector executable +## Make your Amazon Comprehend Connector executable To execute the **Amazon Comprehend Connector**, ensure all mandatory fields are correctly filled. ## 1. Authentication -Choose an authentication type from the **Authentication** dropdown. For details on the different authentication types, refer to the [Appendix](#aws-authentication-types). +Choose an authentication type from the **Authentication** dropdown. For details on the different authentication types, refer to the [appendix](#aws-authentication-types). If you select **Credentials**, the following fields must be provided: - **Access Key**: The AWS access key for a user with Comprehend permissions. - **Secret Key**: The corresponding AWS secret key. -Both **Access Key** and **Secret Key** are required to use the connector. +Both **Access Key** and **Secret Key** are required to use the Connector. ## 2. **Configuration (AWS Region)** After authentication, set the AWS **Region** where the Textract service is hosted: -- **Region**: Specify the region (e.g., `us-east-1`, `eu-west-1`). +- **Region**: Specify the region (for example, `us-east-1`, `eu-west-1`). -> **Note**: Ensure the region matches the location of your Comprehend service and S3 buckets to reduce latency and meet compliance requirements. -> For a full list of AWS regions, refer to [AWS Regional Data](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/). +:::note +Ensure the region matches the location of your Comprehend service and S3 buckets to reduce latency and meet compliance requirements. For a full list of AWS regions, refer to the [AWS regional data](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/). +::: -## 3. Configure Input +## 3. Configure input -### Execution Types +### Execution types Select the desired execution type from the **Execution Type** dropdown. The following options are available: - **Sync** -Use **Sync** execution for creates a classification request to analyze a single document in real-time. +Use **Sync** execution to create a classification request and analyze a single document in real-time. For more details, refer to [sync execution](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ClassifyDocument.html). - **Async** -Use **Async** execution to starts an asynchronous document classification job using a custom classification model. This method allows you to submit a document for analysis and receive results at a later time, making it ideal for background processing or batch operations. +Use **Async** execution to start an asynchronous document classification job using a custom classification model. This method allows you to submit a document for analysis and receive results at a later time, making it ideal for background processing or batch operations. **Async** execution enables you to process documents without waiting for immediate responses. This is particularly useful for larger files or when handling multiple documents simultaneously. For more details on the fields that can be configured during asynchronous execution, refer to [async execution](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartDocumentClassificationJob.html). -### Sync execution fields: - -- **Text (mandatory)** The document text to be analyzed. -- **Document read action** This field defines the Amazon Textract API operation that Amazon Comprehend uses to extract text from PDF files and image files. For more details, refer to [Document read action](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadAction). -- **Document read mode** Determines the text extraction actions for PDF files. For more details, refer to [Document read mode](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadMode). -- **Analyze tables** Returns additional information about any tables that are detected in the input document. For more details, refer to [Feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). -- **Analyze forms** Returns additional information about any forms that are detected in the input document. For more details, refer to [Feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). -- **Endpoint Arn (mandatory)** The Amazon Resource Number (ARN) of the endpoint. For more details, refer to [Classify Document](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ClassifyDocument.html#API_ClassifyDocument_RequestSyntax). - -### Async execution fields: - -- **Document read action** This field defines the Amazon Textract API operation that Amazon Comprehend uses to extract text from PDF files and image files. For more details, refer to [Document read action](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadAction). -- **Document read mode** Determines the text extraction actions for PDF files. For more details, refer to [Document read mode](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadMode). -- **Analyze tables** Returns additional information about any tables that are detected in the input document. For more details, refer to [Feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). -- **Analyze forms** Returns additional information about any forms that are detected in the input document. For more details, refer to [Feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). -- **Input S3 URI (mandatory)** The Amazon S3 URI for the input data. For more details, refer to [S3 URI](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_InputDataConfig.html#comprehend-Type-InputDataConfig-S3Uri). -- **Input Format** Specifies how the text in an input file should be processed. For more details, refer to [InputFormat](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_InputDataConfig.html#comprehend-Type-InputDataConfig-InputFormat). -- **Client request token** A unique identifier for the request. If you do not set the client request token, Amazon Comprehend generates one. -- **Data access role ARN (mandatory)** The Amazon Resource Name (ARN) of the IAM role that grants Amazon Comprehend read access to your input data. -- **Document classifier ARN** The Amazon Resource Name (ARN) of the document classifier to use to process the job. -- **Flywheel ARN** The Amazon Resource Number (ARN) of the flywheel associated with the model to use. -- **Job name** The identifier of the job. -- **Output S3 URI (mandatory)** The Amazon S3 location where you want to write the output data. For more details, refer to [Output data config](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_OutputDataConfig.html). -- **Output Kms Key Id** The id for the AWS Key Management Service (KMS) key that Amazon Comprehend uses to encrypt the output results from an analysis job. For more details, refer to [Output data config](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_OutputDataConfig.html). -- **Tags** Tags to associate with the document classification job. A tag is a key-value pair that adds metadata to a resource used by Amazon Comprehend. +### Sync execution fields + +- **Text (mandatory)**: The document text to be analyzed. +- **Document read action**: This field defines the Amazon Textract API operation that Amazon Comprehend uses to extract text from PDF files and image files. For more details, refer to [document read action](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadAction). +- **Document read mode**: Determines the text extraction actions for PDF files. For more details, refer to [document read mode](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadMode). +- **Analyze tables**: Returns additional information about any tables that are detected in the input document. For more details, refer to [feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). +- **Analyze forms**: Returns additional information about any forms that are detected in the input document. For more details, refer to [feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). +- **Endpoint Arn (mandatory)**: The Amazon Resource Number (ARN) of the endpoint. For more details, refer to [Classify Document](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ClassifyDocument.html#API_ClassifyDocument_RequestSyntax). + +### Async execution fields + +- **Document read action**: This field defines the Amazon Textract API operation that Amazon Comprehend uses to extract text from PDF files and image files. For more details, refer to [document read action](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadAction). +- **Document read mode**: Determines the text extraction actions for PDF files. For more details, refer to [document read mode](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadMode). +- **Analyze tables**: Returns additional information about any tables that are detected in the input document. For more details, refer to [feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). +- **Analyze forms**: Returns additional information about any forms that are detected in the input document. For more details, refer to [feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). +- **Input S3 URI (mandatory)**: The Amazon S3 URI for the input data. For more details, refer to [S3 URI](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_InputDataConfig.html#comprehend-Type-InputDataConfig-S3Uri). +- **Input Format**: Specifies how the text in an input file should be processed. For more details, refer to [InputFormat](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_InputDataConfig.html#comprehend-Type-InputDataConfig-InputFormat). +- **Client request token**: A unique identifier for the request. If you do not set the client request token, Amazon Comprehend generates one. +- **Data access role ARN (mandatory)**: The Amazon Resource Name (ARN) of the IAM role that grants Amazon Comprehend read access to your input data. +- **Document classifier ARN**: The Amazon Resource Name (ARN) of the document classifier to use to process the job. +- **Flywheel ARN**: The Amazon Resource Number (ARN) of the flywheel associated with the model to use. +- **Job name**: The identifier of the job. +- **Output S3 URI (mandatory)**: The Amazon S3 location where you want to write the output data. For more details, refer to [output data config](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_OutputDataConfig.html). +- **Output Kms Key Id**: The ID for the AWS Key Management Service (KMS) key that Amazon Comprehend uses to encrypt the output results from an analysis job. For more details, refer to [output data config](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_OutputDataConfig.html). +- **Tags**: Tags to associate with the document classification job. A tag is a key-value pair that adds metadata to a resource used by Amazon Comprehend. **Example:** ```feel = {"status": "active"} ``` -- **Volume Kms Key Id** ID for the AWS Key Management Service (KMS) key that Amazon Comprehend uses to encrypt data on the storage volume attached to the ML compute instance(s) that process the analysis job. -- **Security group ids** The ID number for a security group on an instance of your private VPC. For more details, refer to [Security group](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_VpcConfig.html#comprehend-Type-VpcConfig-SecurityGroupIds). **Example:** +- **Volume Kms Key Id**: ID for the AWS Key Management Service (KMS) key that Amazon Comprehend uses to encrypt data on the storage volume attached to the ML compute instance(s) that process the analysis job. +- **Security group ids**: The ID number for a security group on an instance of your private VPC. For more details, refer to [security group](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_VpcConfig.html#comprehend-Type-VpcConfig-SecurityGroupIds). + **Example:** ```feel = ["sg-07a2cc6d96e4ec178"] ``` -- **Subnets** The ID for each subnet being used in your private VPC. For more details, refer to [Subnets](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_VpcConfig.html#comprehend-Type-VpcConfig-Subnets). +- **Subnets**: The ID for each subnet being used in your private VPC. For more details, refer to [Subnets](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_VpcConfig.html#comprehend-Type-VpcConfig-Subnets). **Example:** ```feel @@ -116,21 +118,21 @@ For more details on the fields that can be configured during asynchronous execut ``` :::note -To use **VPC** you need at last one vpc endpoint For more details, refer to [Create a VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint-aws). +To use **VPC** you need at last one VPC endpoint For more details, refer to [create a VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint-aws). ::: -## Amazon Comprehend Connector Response +## Amazon Comprehend Connector response The response from the **Amazon Comprehend Connector** will mirror the AWS Comprehend service’s response. The type of response you receive depends on the execution mode selected: - **[Sync Response](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ClassifyDocument.html#API_ClassifyDocument_ResponseSyntax)**: Provides immediate analysis for provided text. - **[Asynchronous Response](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartDocumentClassificationJob.html#API_StartDocumentClassificationJob_ResponseSyntax)**: Used for batch processing where results are returned later through job completion. -### Using the Comprehend Connector Response in Your Process +### Using the Comprehend Connector response in your process -The **Amazon Comprehend Connector** provides the same response structure as the AWS Comprehend API. You can map fields from the response to process variables, depending on your needs. Here's an example of how to extract specific fields using **Result Expression** and **Result Variable**. +The **Amazon Comprehend Connector** provides the same response structure as the AWS Comprehend API. You can map fields from the response to process variables, depending on your needs. Here's an example of how to extract specific fields using **Result Expression** and **Result Variable**: -### Example Comprehend Response (Real-time Execution) +### Example Comprehend response (real-time execution) Utilize output mapping to align this response with process variables: @@ -160,7 +162,7 @@ Utilize output mapping to align this response with process variables: } ``` -#### Mapping Example +#### Mapping example To store only first **Classes** element information, use the following result **expression**: @@ -182,14 +184,11 @@ Mapped values **result**: ### How do I securely store AWS IAM credentials for my Comprehend Connector? -Store your AWS IAM credentials as **Camunda Secrets** to avoid exposing sensitive information. Follow our [Managing Secrets Guide](components/console/manage-clusters/manage-secrets.md) to learn more. +Store your AWS IAM credentials as **Camunda secrets** to avoid exposing sensitive information. Follow our [managing secrets guide](components/console/manage-clusters/manage-secrets.md) to learn more. -### AWS Authentication Types +### AWS authentication types You can authenticate the **Amazon Comprehend Connector** in two ways: -1. **Credentials**: - Select this option if you have an AWS **Access Key** and **Secret Key**. This method is applicable for both SaaS and Self-Managed users. - -2. **Default Credentials Chain (Hybrid/Self-Managed only)**: - Select this option if your system uses implicit authentication methods like role-based access, environment variables, or files on the target host. This method is applicable only for Self-Managed or Hybrid environments. It uses the [Default Credential Provider Chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html) to resolve credentials. +- **Credentials**: Select this option if you have an AWS **Access Key** and **Secret Key**. This method is applicable for both SaaS and Self-Managed users. +- **Default Credentials Chain (Hybrid/Self-Managed only)**: Select this option if your system uses implicit authentication methods like role-based access, environment variables, or files on the target host. This method is applicable only for Self-Managed or Hybrid environments. It uses the [Default Credential Provider Chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html) to resolve credentials. diff --git a/docs/components/connectors/out-of-the-box-connectors/available-connectors-overview.md b/docs/components/connectors/out-of-the-box-connectors/available-connectors-overview.md index 5ddfe34054..bea9850bab 100644 --- a/docs/components/connectors/out-of-the-box-connectors/available-connectors-overview.md +++ b/docs/components/connectors/out-of-the-box-connectors/available-connectors-overview.md @@ -27,13 +27,13 @@ import TabItem from "@theme/TabItem"; ## Outbound Connectors +- [Amazon Comprehend Connector](/components/connectors/out-of-the-box-connectors/amazon-comprehend.md) - Interact with the [Amazon Comprehend service](https://aws.amazon.com/comprehend/) from your BPMN process. - [Amazon DynamoDB Connector](/components/connectors/out-of-the-box-connectors/amazon-dynamodb.md) - Interact with [Amazon DynamoDB NoSQL database service](https://aws.amazon.com/dynamodb/) within your BPMN process, enabling you to store and retrieve data from tables, as well as perform queries and scans. - [Amazon EventBridge Service Connector](/components/connectors/out-of-the-box-connectors/amazon-eventbridge.md) - Send events using [Amazon EventBridge service](https://aws.amazon.com/eventbridge/) within your BPMN process. - [Amazon SageMaker Connector](/components/connectors/out-of-the-box-connectors/amazon-eventbridge.md) - Interact with the [Amazon SageMaker service](https://aws.amazon.com/sagemaker/) from your BPMN process. - [Amazon SNS Outbound Connector](/components/connectors/out-of-the-box-connectors/amazon-sns.md) - Send messages to [Amazon Simple Notification Service](https://aws.amazon.com/sns/) from your BPMN process. - [Amazon SQS Connector](/components/connectors/out-of-the-box-connectors/amazon-sqs.md) - Send messages to [Amazon Simple Queue Service](https://aws.amazon.com/sqs/) from your BPMN process. - [Amazon Textract Connector](components/connectors/out-of-the-box-connectors/amazon-textract.md) - Interact with the [Amazon Textract Service](https://aws.amazon.com/textract/) from your BPMN process. -- [Amazon Comprehend Connector](/components/connectors/out-of-the-box-connectors/amazon-comprehend.md) - Interact with the [Amazon Comprehend service](https://aws.amazon.com/comprehend/) from your BPMN process. - [Asana Connector](/components/connectors/out-of-the-box-connectors/asana.md) - Manage [Asana](https://asana.com/) projects and tasks from your BPMN process. - [Automation Anywhere Connector](/components/connectors/out-of-the-box-connectors/automation-anywhere.md) - Orchestrate your [Automation Anywhere](https://www.automationanywhere.com/) queue from your BPMN process. - [AWS Lambda Connector](/components/connectors/out-of-the-box-connectors/aws-lambda.md) - Invoke [AWS Lambda Functions](https://aws.amazon.com/lambda/) from your BPMN process. diff --git a/optimize_sidebars.js b/optimize_sidebars.js index 8777cb245a..03f10d2df8 100644 --- a/optimize_sidebars.js +++ b/optimize_sidebars.js @@ -898,6 +898,10 @@ module.exports = { "AWS Bedrock Connector", "components/connectors/out-of-the-box-connectors/amazon-bedrock/" ), + docsLink( + "AWS Comprehend Connector", + "/components/connectors/out-of-the-box-connectors/amazon-comprehend/" + ), docsLink( "AWS DynamoDB Connector", "components/connectors/out-of-the-box-connectors/amazon-dynamodb/" @@ -922,10 +926,6 @@ module.exports = { "AWS SQS Connector", "components/connectors/out-of-the-box-connectors/amazon-sqs/" ), - docsLink( - "AWS Comprehend Connector", - "/components/connectors/out-of-the-box-connectors/amazon-comprehend/" - ), docsLink( "AWS Textract Connector", "components/connectors/out-of-the-box-connectors/amazon-textract/" diff --git a/sidebars.js b/sidebars.js index 2dfe148d71..c15a6610ed 100644 --- a/sidebars.js +++ b/sidebars.js @@ -320,6 +320,7 @@ module.exports = { { AWS: [ "components/connectors/out-of-the-box-connectors/amazon-bedrock", + "components/connectors/out-of-the-box-connectors/amazon-comprehend", "components/connectors/out-of-the-box-connectors/amazon-dynamodb", "components/connectors/out-of-the-box-connectors/amazon-eventbridge", "components/connectors/out-of-the-box-connectors/aws-lambda", From 9cbcc0adc5bccc2e66429e03415aa590746bd463 Mon Sep 17 00:00:00 2001 From: Christina Ausley Date: Mon, 7 Oct 2024 12:36:38 -0400 Subject: [PATCH 3/5] adjust sidebar --- sidebars.js | 1 - 1 file changed, 1 deletion(-) diff --git a/sidebars.js b/sidebars.js index c15a6610ed..874de7a0a8 100644 --- a/sidebars.js +++ b/sidebars.js @@ -328,7 +328,6 @@ module.exports = { "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-textract", - "components/connectors/out-of-the-box-connectors/amazon-comprehend", ], }, "components/connectors/out-of-the-box-connectors/blueprism", From 519ded25f12a235306f66e02600551e0ad6648dc Mon Sep 17 00:00:00 2001 From: Christina Ausley Date: Tue, 8 Oct 2024 07:47:10 -0400 Subject: [PATCH 4/5] backport --- .../version-3.14.0-sidebars.json | 5 + .../amazon-comprehend.md | 194 ++++++++++++++++++ .../available-connectors-overview.md | 1 + versioned_sidebars/version-8.6-sidebars.json | 1 + 4 files changed, 201 insertions(+) create mode 100644 versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/amazon-comprehend.md diff --git a/optimize_versioned_sidebars/version-3.14.0-sidebars.json b/optimize_versioned_sidebars/version-3.14.0-sidebars.json index 83b60563c1..5ab2706f29 100644 --- a/optimize_versioned_sidebars/version-3.14.0-sidebars.json +++ b/optimize_versioned_sidebars/version-3.14.0-sidebars.json @@ -1158,6 +1158,11 @@ "label": "AWS Bedrock Connector", "href": "/docs/components/connectors/out-of-the-box-connectors/amazon-bedrock/" }, + { + "type": "link", + "label": "AWS Comprehend Connector", + "href": "/docs/components/connectors/out-of-the-box-connectors/amazon-comprehend/" + }, { "type": "link", "label": "AWS DynamoDB Connector", diff --git a/versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/amazon-comprehend.md b/versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/amazon-comprehend.md new file mode 100644 index 0000000000..664fd950d4 --- /dev/null +++ b/versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/amazon-comprehend.md @@ -0,0 +1,194 @@ +--- +id: amazon-comprehend +title: Amazon Comprehend Connector +sidebar_label: AWS Comprehend Connector +description: Use the Amazon Comprehend Connector to extract insights from the content of your documents, like key phrases and personal identifiable information. +--- + +:::info +The **Amazon Comprehend Connector** is available for `8.6.0` or later. +::: + +The **Amazon Comprehend Connector** allows you to integrate your BPMN service with [Amazon Comprehend](https://docs.aws.amazon.com/comprehend/latest/dg/what-is.html), a service which extracts insights about the content of documents, such as personal identifiable information and key phrases. + +## Prerequisites + +To use the **Amazon Comprehend Connector**, you must have an **AWS IAM Access Key** and **Secret Key** with the appropriate Comprehend permissions. Refer to the [AWS Comprehend set up instructions](https://docs.aws.amazon.com/comprehend/latest/dg/setting-up.html). + +:::note +Use **Camunda secrets** to avoid exposing your AWS IAM credentials as plain text. +Refer to [managing secrets](components/console/manage-clusters/manage-secrets.md) for more details. +::: + +## Create an Amazon Comprehend Connector task + +import ConnectorTask from '../../../components/react-components/connector-task.md' + + + +## Make your Amazon Comprehend Connector executable + +To execute the **Amazon Comprehend Connector**, ensure all mandatory fields are correctly filled. + +## 1. Authentication + +Choose an authentication type from the **Authentication** dropdown. For details on the different authentication types, refer to the [appendix](#aws-authentication-types). + +If you select **Credentials**, the following fields must be provided: + +- **Access Key**: The AWS access key for a user with Comprehend permissions. +- **Secret Key**: The corresponding AWS secret key. + +Both **Access Key** and **Secret Key** are required to use the Connector. + +## 2. **Configuration (AWS Region)** + +After authentication, set the AWS **Region** where the Textract service is hosted: + +- **Region**: Specify the region (for example, `us-east-1`, `eu-west-1`). + +:::note +Ensure the region matches the location of your Comprehend service and S3 buckets to reduce latency and meet compliance requirements. For a full list of AWS regions, refer to the [AWS regional data](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/). +::: + +## 3. Configure input + +### Execution types + +Select the desired execution type from the **Execution Type** dropdown. The following options are available: + +- **Sync** + +Use **Sync** execution to create a classification request and analyze a single document in real-time. + +For more details, refer to [sync execution](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ClassifyDocument.html). + +- **Async** + +Use **Async** execution to start an asynchronous document classification job using a custom classification model. This method allows you to submit a document for analysis and receive results at a later time, making it ideal for background processing or batch operations. + +**Async** execution enables you to process documents without waiting for immediate responses. This is particularly useful for larger files or when handling multiple documents simultaneously. + +For more details on the fields that can be configured during asynchronous execution, refer to [async execution](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartDocumentClassificationJob.html). + +### Sync execution fields + +- **Text (mandatory)**: The document text to be analyzed. +- **Document read action**: This field defines the Amazon Textract API operation that Amazon Comprehend uses to extract text from PDF files and image files. For more details, refer to [document read action](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadAction). +- **Document read mode**: Determines the text extraction actions for PDF files. For more details, refer to [document read mode](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadMode). +- **Analyze tables**: Returns additional information about any tables that are detected in the input document. For more details, refer to [feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). +- **Analyze forms**: Returns additional information about any forms that are detected in the input document. For more details, refer to [feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). +- **Endpoint Arn (mandatory)**: The Amazon Resource Number (ARN) of the endpoint. For more details, refer to [Classify Document](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ClassifyDocument.html#API_ClassifyDocument_RequestSyntax). + +### Async execution fields + +- **Document read action**: This field defines the Amazon Textract API operation that Amazon Comprehend uses to extract text from PDF files and image files. For more details, refer to [document read action](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadAction). +- **Document read mode**: Determines the text extraction actions for PDF files. For more details, refer to [document read mode](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadMode). +- **Analyze tables**: Returns additional information about any tables that are detected in the input document. For more details, refer to [feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). +- **Analyze forms**: Returns additional information about any forms that are detected in the input document. For more details, refer to [feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). +- **Input S3 URI (mandatory)**: The Amazon S3 URI for the input data. For more details, refer to [S3 URI](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_InputDataConfig.html#comprehend-Type-InputDataConfig-S3Uri). +- **Input Format**: Specifies how the text in an input file should be processed. For more details, refer to [InputFormat](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_InputDataConfig.html#comprehend-Type-InputDataConfig-InputFormat). +- **Client request token**: A unique identifier for the request. If you do not set the client request token, Amazon Comprehend generates one. +- **Data access role ARN (mandatory)**: The Amazon Resource Name (ARN) of the IAM role that grants Amazon Comprehend read access to your input data. +- **Document classifier ARN**: The Amazon Resource Name (ARN) of the document classifier to use to process the job. +- **Flywheel ARN**: The Amazon Resource Number (ARN) of the flywheel associated with the model to use. +- **Job name**: The identifier of the job. +- **Output S3 URI (mandatory)**: The Amazon S3 location where you want to write the output data. For more details, refer to [output data config](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_OutputDataConfig.html). +- **Output Kms Key Id**: The ID for the AWS Key Management Service (KMS) key that Amazon Comprehend uses to encrypt the output results from an analysis job. For more details, refer to [output data config](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_OutputDataConfig.html). +- **Tags**: Tags to associate with the document classification job. A tag is a key-value pair that adds metadata to a resource used by Amazon Comprehend. + **Example:** + +```feel += {"status": "active"} +``` + +- **Volume Kms Key Id**: ID for the AWS Key Management Service (KMS) key that Amazon Comprehend uses to encrypt data on the storage volume attached to the ML compute instance(s) that process the analysis job. +- **Security group ids**: The ID number for a security group on an instance of your private VPC. For more details, refer to [security group](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_VpcConfig.html#comprehend-Type-VpcConfig-SecurityGroupIds). + **Example:** + +```feel += ["sg-07a2cc6d96e4ec178"] +``` + +- **Subnets**: The ID for each subnet being used in your private VPC. For more details, refer to [Subnets](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_VpcConfig.html#comprehend-Type-VpcConfig-Subnets). + **Example:** + +```feel += ["subnet-013eac53274e1d93f"] +``` + +:::note +To use **VPC** you need at last one VPC endpoint For more details, refer to [create a VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint-aws). +::: + +## Amazon Comprehend Connector response + +The response from the **Amazon Comprehend Connector** will mirror the AWS Comprehend service’s response. The type of response you receive depends on the execution mode selected: + +- **[Sync Response](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ClassifyDocument.html#API_ClassifyDocument_ResponseSyntax)**: Provides immediate analysis for provided text. +- **[Asynchronous Response](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartDocumentClassificationJob.html#API_StartDocumentClassificationJob_ResponseSyntax)**: Used for batch processing where results are returned later through job completion. + +### Using the Comprehend Connector response in your process + +The **Amazon Comprehend Connector** provides the same response structure as the AWS Comprehend API. You can map fields from the response to process variables, depending on your needs. Here's an example of how to extract specific fields using **Result Expression** and **Result Variable**: + +### Example Comprehend response (real-time execution) + +Utilize output mapping to align this response with process variables: + +1. Use **Result Variable** to store the response in a process variable. For example, `myResultVariable`. This approach stores the entire Comprehend message as a process variable named `myResultVariable`. +2. Use **Result Expression** to map fields from the response into process variables. This approach allows for more granularity. Instead of storing the entire response in one variable, you can extract specific fields from the **Comprehend Connector** message and assign them to different process variables. This is particularly useful when you are only interested in certain parts of the message, or when different parts of the message need to be used separately in your process. + Example: + +```json +{ + "classes": [ + { + "name": "CHECKING_AC", + "score": 0.5423, + "page": null + }, + { + "name": "SAVINGS_AC", + "score": 0.4577, + "page": null + } + ], + "labels": null, + "documentMetadata": null, + "documentType": null, + "errors": null, + "warnings": null +} +``` + +#### Mapping example + +To store only first **Classes** element information, use the following result **expression**: + +```feel += {classInfo: classes[1]} +``` + +Mapped values **result**: + +```json +{ + "name": "CHECKING_AC", + "score": 0.5422999858856201, + "page": null +} +``` + +## Appendix & FAQ + +### How do I securely store AWS IAM credentials for my Comprehend Connector? + +Store your AWS IAM credentials as **Camunda secrets** to avoid exposing sensitive information. Follow our [managing secrets guide](components/console/manage-clusters/manage-secrets.md) to learn more. + +### AWS authentication types + +You can authenticate the **Amazon Comprehend Connector** in two ways: + +- **Credentials**: Select this option if you have an AWS **Access Key** and **Secret Key**. This method is applicable for both SaaS and Self-Managed users. +- **Default Credentials Chain (Hybrid/Self-Managed only)**: Select this option if your system uses implicit authentication methods like role-based access, environment variables, or files on the target host. This method is applicable only for Self-Managed or Hybrid environments. It uses the [Default Credential Provider Chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html) to resolve credentials. diff --git a/versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/available-connectors-overview.md b/versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/available-connectors-overview.md index 0b473e9aa6..93782940b3 100644 --- a/versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/available-connectors-overview.md +++ b/versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/available-connectors-overview.md @@ -28,6 +28,7 @@ import TabItem from "@theme/TabItem"; ## Outbound Connectors - [Amazon Bedrock Connector](/components/connectors/out-of-the-box-connectors/amazon-bedrock.md) - Interact with [Amazon Bedrock](https://aws.amazon.com/bedrock/) from your BPMN process to experiment with and evaluate foundation models (FMs) from leading AI companies. +- [Amazon Comprehend Connector](/components/connectors/out-of-the-box-connectors/amazon-comprehend.md) - Interact with the [Amazon Comprehend service](https://aws.amazon.com/comprehend/) from your BPMN process. - [Amazon DynamoDB Connector](/components/connectors/out-of-the-box-connectors/amazon-dynamodb.md) - Interact with [Amazon DynamoDB NoSQL database service](https://aws.amazon.com/dynamodb/) within your BPMN process, enabling you to store and retrieve data from tables, as well as perform queries and scans. - [Amazon EventBridge Service Connector](/components/connectors/out-of-the-box-connectors/amazon-eventbridge.md) - Send events using [Amazon EventBridge service](https://aws.amazon.com/eventbridge/) within your BPMN process. - [Amazon SageMaker Connector](/components/connectors/out-of-the-box-connectors/amazon-eventbridge.md) - Interact with the [Amazon SageMaker service](https://aws.amazon.com/sagemaker/) from your BPMN process. diff --git a/versioned_sidebars/version-8.6-sidebars.json b/versioned_sidebars/version-8.6-sidebars.json index 45af8548ab..c02cfbb07e 100644 --- a/versioned_sidebars/version-8.6-sidebars.json +++ b/versioned_sidebars/version-8.6-sidebars.json @@ -419,6 +419,7 @@ { "AWS": [ "components/connectors/out-of-the-box-connectors/amazon-bedrock", + "components/connectors/out-of-the-box-connectors/amazon-comprehend", "components/connectors/out-of-the-box-connectors/amazon-dynamodb", "components/connectors/out-of-the-box-connectors/amazon-eventbridge", "components/connectors/out-of-the-box-connectors/aws-lambda", From 56b542c8075dacaa5feb58d7929098422d534254 Mon Sep 17 00:00:00 2001 From: Christina Ausley Date: Tue, 8 Oct 2024 10:44:55 -0400 Subject: [PATCH 5/5] remove from 8.6 --- .../amazon-comprehend.md | 2 +- .../version-3.14.0-sidebars.json | 5 - .../amazon-comprehend.md | 194 ------------------ .../available-connectors-overview.md | 1 - versioned_sidebars/version-8.6-sidebars.json | 1 - 5 files changed, 1 insertion(+), 202 deletions(-) delete mode 100644 versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/amazon-comprehend.md diff --git a/docs/components/connectors/out-of-the-box-connectors/amazon-comprehend.md b/docs/components/connectors/out-of-the-box-connectors/amazon-comprehend.md index 664fd950d4..a1e44783cb 100644 --- a/docs/components/connectors/out-of-the-box-connectors/amazon-comprehend.md +++ b/docs/components/connectors/out-of-the-box-connectors/amazon-comprehend.md @@ -6,7 +6,7 @@ description: Use the Amazon Comprehend Connector to extract insights from the co --- :::info -The **Amazon Comprehend Connector** is available for `8.6.0` or later. +The **Amazon Comprehend Connector** is available for `8.7.0` or later. ::: The **Amazon Comprehend Connector** allows you to integrate your BPMN service with [Amazon Comprehend](https://docs.aws.amazon.com/comprehend/latest/dg/what-is.html), a service which extracts insights about the content of documents, such as personal identifiable information and key phrases. diff --git a/optimize_versioned_sidebars/version-3.14.0-sidebars.json b/optimize_versioned_sidebars/version-3.14.0-sidebars.json index 5ab2706f29..83b60563c1 100644 --- a/optimize_versioned_sidebars/version-3.14.0-sidebars.json +++ b/optimize_versioned_sidebars/version-3.14.0-sidebars.json @@ -1158,11 +1158,6 @@ "label": "AWS Bedrock Connector", "href": "/docs/components/connectors/out-of-the-box-connectors/amazon-bedrock/" }, - { - "type": "link", - "label": "AWS Comprehend Connector", - "href": "/docs/components/connectors/out-of-the-box-connectors/amazon-comprehend/" - }, { "type": "link", "label": "AWS DynamoDB Connector", diff --git a/versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/amazon-comprehend.md b/versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/amazon-comprehend.md deleted file mode 100644 index 664fd950d4..0000000000 --- a/versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/amazon-comprehend.md +++ /dev/null @@ -1,194 +0,0 @@ ---- -id: amazon-comprehend -title: Amazon Comprehend Connector -sidebar_label: AWS Comprehend Connector -description: Use the Amazon Comprehend Connector to extract insights from the content of your documents, like key phrases and personal identifiable information. ---- - -:::info -The **Amazon Comprehend Connector** is available for `8.6.0` or later. -::: - -The **Amazon Comprehend Connector** allows you to integrate your BPMN service with [Amazon Comprehend](https://docs.aws.amazon.com/comprehend/latest/dg/what-is.html), a service which extracts insights about the content of documents, such as personal identifiable information and key phrases. - -## Prerequisites - -To use the **Amazon Comprehend Connector**, you must have an **AWS IAM Access Key** and **Secret Key** with the appropriate Comprehend permissions. Refer to the [AWS Comprehend set up instructions](https://docs.aws.amazon.com/comprehend/latest/dg/setting-up.html). - -:::note -Use **Camunda secrets** to avoid exposing your AWS IAM credentials as plain text. -Refer to [managing secrets](components/console/manage-clusters/manage-secrets.md) for more details. -::: - -## Create an Amazon Comprehend Connector task - -import ConnectorTask from '../../../components/react-components/connector-task.md' - - - -## Make your Amazon Comprehend Connector executable - -To execute the **Amazon Comprehend Connector**, ensure all mandatory fields are correctly filled. - -## 1. Authentication - -Choose an authentication type from the **Authentication** dropdown. For details on the different authentication types, refer to the [appendix](#aws-authentication-types). - -If you select **Credentials**, the following fields must be provided: - -- **Access Key**: The AWS access key for a user with Comprehend permissions. -- **Secret Key**: The corresponding AWS secret key. - -Both **Access Key** and **Secret Key** are required to use the Connector. - -## 2. **Configuration (AWS Region)** - -After authentication, set the AWS **Region** where the Textract service is hosted: - -- **Region**: Specify the region (for example, `us-east-1`, `eu-west-1`). - -:::note -Ensure the region matches the location of your Comprehend service and S3 buckets to reduce latency and meet compliance requirements. For a full list of AWS regions, refer to the [AWS regional data](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/). -::: - -## 3. Configure input - -### Execution types - -Select the desired execution type from the **Execution Type** dropdown. The following options are available: - -- **Sync** - -Use **Sync** execution to create a classification request and analyze a single document in real-time. - -For more details, refer to [sync execution](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ClassifyDocument.html). - -- **Async** - -Use **Async** execution to start an asynchronous document classification job using a custom classification model. This method allows you to submit a document for analysis and receive results at a later time, making it ideal for background processing or batch operations. - -**Async** execution enables you to process documents without waiting for immediate responses. This is particularly useful for larger files or when handling multiple documents simultaneously. - -For more details on the fields that can be configured during asynchronous execution, refer to [async execution](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartDocumentClassificationJob.html). - -### Sync execution fields - -- **Text (mandatory)**: The document text to be analyzed. -- **Document read action**: This field defines the Amazon Textract API operation that Amazon Comprehend uses to extract text from PDF files and image files. For more details, refer to [document read action](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadAction). -- **Document read mode**: Determines the text extraction actions for PDF files. For more details, refer to [document read mode](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadMode). -- **Analyze tables**: Returns additional information about any tables that are detected in the input document. For more details, refer to [feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). -- **Analyze forms**: Returns additional information about any forms that are detected in the input document. For more details, refer to [feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). -- **Endpoint Arn (mandatory)**: The Amazon Resource Number (ARN) of the endpoint. For more details, refer to [Classify Document](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ClassifyDocument.html#API_ClassifyDocument_RequestSyntax). - -### Async execution fields - -- **Document read action**: This field defines the Amazon Textract API operation that Amazon Comprehend uses to extract text from PDF files and image files. For more details, refer to [document read action](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadAction). -- **Document read mode**: Determines the text extraction actions for PDF files. For more details, refer to [document read mode](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-DocumentReadMode). -- **Analyze tables**: Returns additional information about any tables that are detected in the input document. For more details, refer to [feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). -- **Analyze forms**: Returns additional information about any forms that are detected in the input document. For more details, refer to [feature types](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DocumentReaderConfig.html#comprehend-Type-DocumentReaderConfig-FeatureTypes). -- **Input S3 URI (mandatory)**: The Amazon S3 URI for the input data. For more details, refer to [S3 URI](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_InputDataConfig.html#comprehend-Type-InputDataConfig-S3Uri). -- **Input Format**: Specifies how the text in an input file should be processed. For more details, refer to [InputFormat](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_InputDataConfig.html#comprehend-Type-InputDataConfig-InputFormat). -- **Client request token**: A unique identifier for the request. If you do not set the client request token, Amazon Comprehend generates one. -- **Data access role ARN (mandatory)**: The Amazon Resource Name (ARN) of the IAM role that grants Amazon Comprehend read access to your input data. -- **Document classifier ARN**: The Amazon Resource Name (ARN) of the document classifier to use to process the job. -- **Flywheel ARN**: The Amazon Resource Number (ARN) of the flywheel associated with the model to use. -- **Job name**: The identifier of the job. -- **Output S3 URI (mandatory)**: The Amazon S3 location where you want to write the output data. For more details, refer to [output data config](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_OutputDataConfig.html). -- **Output Kms Key Id**: The ID for the AWS Key Management Service (KMS) key that Amazon Comprehend uses to encrypt the output results from an analysis job. For more details, refer to [output data config](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_OutputDataConfig.html). -- **Tags**: Tags to associate with the document classification job. A tag is a key-value pair that adds metadata to a resource used by Amazon Comprehend. - **Example:** - -```feel -= {"status": "active"} -``` - -- **Volume Kms Key Id**: ID for the AWS Key Management Service (KMS) key that Amazon Comprehend uses to encrypt data on the storage volume attached to the ML compute instance(s) that process the analysis job. -- **Security group ids**: The ID number for a security group on an instance of your private VPC. For more details, refer to [security group](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_VpcConfig.html#comprehend-Type-VpcConfig-SecurityGroupIds). - **Example:** - -```feel -= ["sg-07a2cc6d96e4ec178"] -``` - -- **Subnets**: The ID for each subnet being used in your private VPC. For more details, refer to [Subnets](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_VpcConfig.html#comprehend-Type-VpcConfig-Subnets). - **Example:** - -```feel -= ["subnet-013eac53274e1d93f"] -``` - -:::note -To use **VPC** you need at last one VPC endpoint For more details, refer to [create a VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint-aws). -::: - -## Amazon Comprehend Connector response - -The response from the **Amazon Comprehend Connector** will mirror the AWS Comprehend service’s response. The type of response you receive depends on the execution mode selected: - -- **[Sync Response](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_ClassifyDocument.html#API_ClassifyDocument_ResponseSyntax)**: Provides immediate analysis for provided text. -- **[Asynchronous Response](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartDocumentClassificationJob.html#API_StartDocumentClassificationJob_ResponseSyntax)**: Used for batch processing where results are returned later through job completion. - -### Using the Comprehend Connector response in your process - -The **Amazon Comprehend Connector** provides the same response structure as the AWS Comprehend API. You can map fields from the response to process variables, depending on your needs. Here's an example of how to extract specific fields using **Result Expression** and **Result Variable**: - -### Example Comprehend response (real-time execution) - -Utilize output mapping to align this response with process variables: - -1. Use **Result Variable** to store the response in a process variable. For example, `myResultVariable`. This approach stores the entire Comprehend message as a process variable named `myResultVariable`. -2. Use **Result Expression** to map fields from the response into process variables. This approach allows for more granularity. Instead of storing the entire response in one variable, you can extract specific fields from the **Comprehend Connector** message and assign them to different process variables. This is particularly useful when you are only interested in certain parts of the message, or when different parts of the message need to be used separately in your process. - Example: - -```json -{ - "classes": [ - { - "name": "CHECKING_AC", - "score": 0.5423, - "page": null - }, - { - "name": "SAVINGS_AC", - "score": 0.4577, - "page": null - } - ], - "labels": null, - "documentMetadata": null, - "documentType": null, - "errors": null, - "warnings": null -} -``` - -#### Mapping example - -To store only first **Classes** element information, use the following result **expression**: - -```feel -= {classInfo: classes[1]} -``` - -Mapped values **result**: - -```json -{ - "name": "CHECKING_AC", - "score": 0.5422999858856201, - "page": null -} -``` - -## Appendix & FAQ - -### How do I securely store AWS IAM credentials for my Comprehend Connector? - -Store your AWS IAM credentials as **Camunda secrets** to avoid exposing sensitive information. Follow our [managing secrets guide](components/console/manage-clusters/manage-secrets.md) to learn more. - -### AWS authentication types - -You can authenticate the **Amazon Comprehend Connector** in two ways: - -- **Credentials**: Select this option if you have an AWS **Access Key** and **Secret Key**. This method is applicable for both SaaS and Self-Managed users. -- **Default Credentials Chain (Hybrid/Self-Managed only)**: Select this option if your system uses implicit authentication methods like role-based access, environment variables, or files on the target host. This method is applicable only for Self-Managed or Hybrid environments. It uses the [Default Credential Provider Chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html) to resolve credentials. diff --git a/versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/available-connectors-overview.md b/versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/available-connectors-overview.md index 93782940b3..0b473e9aa6 100644 --- a/versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/available-connectors-overview.md +++ b/versioned_docs/version-8.6/components/connectors/out-of-the-box-connectors/available-connectors-overview.md @@ -28,7 +28,6 @@ import TabItem from "@theme/TabItem"; ## Outbound Connectors - [Amazon Bedrock Connector](/components/connectors/out-of-the-box-connectors/amazon-bedrock.md) - Interact with [Amazon Bedrock](https://aws.amazon.com/bedrock/) from your BPMN process to experiment with and evaluate foundation models (FMs) from leading AI companies. -- [Amazon Comprehend Connector](/components/connectors/out-of-the-box-connectors/amazon-comprehend.md) - Interact with the [Amazon Comprehend service](https://aws.amazon.com/comprehend/) from your BPMN process. - [Amazon DynamoDB Connector](/components/connectors/out-of-the-box-connectors/amazon-dynamodb.md) - Interact with [Amazon DynamoDB NoSQL database service](https://aws.amazon.com/dynamodb/) within your BPMN process, enabling you to store and retrieve data from tables, as well as perform queries and scans. - [Amazon EventBridge Service Connector](/components/connectors/out-of-the-box-connectors/amazon-eventbridge.md) - Send events using [Amazon EventBridge service](https://aws.amazon.com/eventbridge/) within your BPMN process. - [Amazon SageMaker Connector](/components/connectors/out-of-the-box-connectors/amazon-eventbridge.md) - Interact with the [Amazon SageMaker service](https://aws.amazon.com/sagemaker/) from your BPMN process. diff --git a/versioned_sidebars/version-8.6-sidebars.json b/versioned_sidebars/version-8.6-sidebars.json index c02cfbb07e..45af8548ab 100644 --- a/versioned_sidebars/version-8.6-sidebars.json +++ b/versioned_sidebars/version-8.6-sidebars.json @@ -419,7 +419,6 @@ { "AWS": [ "components/connectors/out-of-the-box-connectors/amazon-bedrock", - "components/connectors/out-of-the-box-connectors/amazon-comprehend", "components/connectors/out-of-the-box-connectors/amazon-dynamodb", "components/connectors/out-of-the-box-connectors/amazon-eventbridge", "components/connectors/out-of-the-box-connectors/aws-lambda",