Amazon Comprehend connector

Integrate your BPMN service with Amazon Comprehend to classify documents with a custom classification model.

About this connector

The Amazon Comprehend connector is an outbound connector that connects your BPMN service with Amazon Comprehend, a service that extracts insights about the content of documents, such as personal identifiable information and key phrases. Use it to classify a document as part of a process, for example to route an incoming document based on its class.

The connector supports two execution types:

• Sync: Classifies a single piece of text in real time and returns the result to your process.
• Async: Starts an asynchronous document classification job, for example for larger files or several documents at once, and returns the job details. The job results are written to an Amazon S3 location.

Prerequisites

To use the Amazon Comprehend connector, you need the following:

Prerequisite	Description
AWS IAM user and permissions	An IAM access key and secret key pair with the appropriate Amazon Comprehend permissions. Not required if you use the default credentials chain (hybrid/Self-Managed only) or a saved AWS credential.

note

Use secrets to avoid exposing your AWS IAM credentials as plain text. Refer to managing secrets to learn more.

Use this connector

New to using an outbound connector? Learn how to add and use this type of connector, apply element templates, use connector secrets, handle results and errors, and more.

Use an outbound connector

Configuration

Authentication

Select an authentication method for the connector. Learn more about the available options in AWS authentication types.

Property	Type	Required	Description	Example
AWS credential	Configuration	No	Select a saved AWS credential, which can include a default region. When you select a credential, the Authentication, Access key, and Secret key fields are hidden. Learn more about credentials.
Authentication	Dropdown	Yes	The AWS authentication strategy: Credentials, or Default Credentials Chain (Hybrid/Self-Managed only). Shown when no AWS credential is selected.	Credentials
Access key	String	Yes	IAM access key of a user with the necessary permissions for this connector. Shown when Authentication is Credentials and no AWS credential is selected.	{{secrets.MY_AWS_ACCESS_KEY}}
Secret key	String	Yes	IAM secret key of a user with the necessary permissions for this connector. Shown when Authentication is Credentials and no AWS credential is selected.	{{secrets.MY_AWS_SECRET_KEY}}

Region

Property	Type	Required	Description	Example
Region	String	Yes	The AWS region where your Amazon Comprehend service and S3 buckets are hosted. Choosing the matching region reduces latency and helps you meet compliance requirements. Refer to AWS regional data for a list of regions. When you select an AWS credential, this field is optional: it overrides the credential's default region, and is required if the credential has no default region.	us-east-1

AWS authentication types

You can authenticate the connector with AWS in the following ways:

• Credentials: Use this option if your AWS account administrator provided a pair of access and secret keys. It applies to SaaS and Self-Managed.
• Default Credentials Chain (Hybrid/Self-Managed only): Use this option if your system relies on an implicit authentication mechanism, such as role-based authentication, credentials supplied through environment variables, or files on the target host. It applies only to Self-Managed or hybrid distributions, and uses the Default Credential Provider Chain to resolve credentials.
• AWS credential: Select a saved credential instead of entering authentication details on the task.

Operations

Select the operation with the Execution type dropdown. The available input parameters depend on your selection.

Property	Type	Required	Description	Example
Execution type	Dropdown	Yes	Sync classifies a single piece of text in real time. Async starts a document classification job.	Sync

Classify a document (Sync)

Create a classification request and analyze a single document in real time. For more details, refer to the ClassifyDocument API.

Input parameters

Property	Type	Required	Description	Example
Text	String	Yes	The text to be analyzed.
Endpoint's ARN	String	Yes	The Amazon Resource Name (ARN) of the custom model endpoint used to run the classification.	arn:aws:comprehend:us-east-1:123456789012:document-classifier-endpoint/my-endpoint

Output

The connector response mirrors the ClassifyDocument response of the AWS Comprehend service. It contains the following fields:

Field	Description
sdkResponseMetadata	Metadata of the AWS response, such as the requestId.
sdkHttpMetadata	The HTTP status code and headers of the AWS response.
classes	The classes of the document, each with a name, a score, and the page it applies to.
labels	The labels of the document, each with a name, a score, and the page it applies to.
documentMetadata	The number of pages and the extracted characters per page.
documentType	The document type per page.
errors	Page-level errors reported by Amazon Comprehend.
warnings	Page-level warnings reported by Amazon Comprehend.

Fields that Amazon Comprehend does not return are null. For example, a response for a classifier that returns classes:

{
  "sdkResponseMetadata": {
    "requestId": "929bf054-193b-48e6-ab80-3aeeb613b415"
  },
  "sdkHttpMetadata": {
    "httpHeaders": { "Content-Type": "application/x-amz-json-1.1" },
    "httpStatusCode": 200,
    "allHttpHeaders": { "Content-Type": ["application/x-amz-json-1.1"] }
  },
  "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
}

To map the response into process variables, use Result variable to store the whole response, or Result expression to map individual fields. For example, to store only the first element of classes:

= {classInfo: response.classes[1]}

Start a classification job (Async)

Start an asynchronous document classification job using a custom classification model. Use this operation to submit documents for analysis and receive the results later, which suits background processing, larger files, or handling several documents at once. For more details, refer to the StartDocumentClassificationJob API.

Input parameters

Property	Type	Required	Description	Example
Document read mode	Dropdown	Yes	Determines the text extraction actions for PDF files: Service default, Force document read action, or None. Defaults to Service default.	Service default
Document read action	Dropdown	Yes	The Amazon Textract API operation that Amazon Comprehend uses to extract text from PDF files and image files: Detect document text, Analyze document, or None. For more details, refer to document read action. Defaults to Detect document text.	Detect document text
Analyze tables	Boolean	No	Returns additional information about any tables that are detected in the input document. Shown when Document read action is Analyze document. For more details, refer to feature types.
Analyze forms	Boolean	No	Returns additional information about any forms that are detected in the input document. Shown when Document read action is Analyze document. For more details, refer to feature types.
Inputs' S3 URI	String	Yes	The Amazon S3 URI for the input data.	s3://my-input-bucket/documents/
Input file processing mode	Dropdown	Yes	Specifies how the text in an input file is processed: Each file is considered a separate document, Each line in a file is considered a separate document, or None. Defaults to Each file is considered a separate document.	Each file is considered a separate document
Client request token	String	No	A unique identifier for the request. If you do not set the client request token, Amazon Comprehend generates one.
Data Access Role's ARN	String	Yes	The ARN of the IAM role that grants Amazon Comprehend read access to your input data.	arn:aws:iam::123456789012:role/comprehend-data-access-role
Document Classifier's ARN	String	Yes	The ARN of the document classifier to use to process the job.	arn:aws:comprehend:us-east-1:123456789012:document-classifier/my-classifier
Flywheel's ARN	String	No	The ARN of the flywheel that orchestrates training and versioning of the classification model.
Job name	String	No	The identifier of the job.
Output's S3 URI	String	Yes	The Amazon S3 location where you want to write the output data.	s3://my-output-bucket/results/
Outputs KMS Key Id	String	No	The ID of the AWS Key Management Service (KMS) key that Amazon Comprehend uses to encrypt the output results of the job.
Tags	String	No	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. Provide a FEEL expression.	= {"status": "active"}
VolumeKmsKeyId	String	No	The ID of the KMS key that Amazon Comprehend uses to encrypt data on the storage volume attached to the ML compute instances that process the job.
Security group Ids	String	No	The ID of each security group on an instance of your private VPC. Provide a FEEL expression.	= ["sg-07a2cc6d96e4ec178"]
Subnets	String	No	The ID of each subnet used in your private VPC. Provide a FEEL expression.	= ["subnet-013eac53274e1d93f"]

note

To use a VPC, you need at least one VPC endpoint. For more details, refer to create a VPC endpoint.

Output

The connector response mirrors the StartDocumentClassificationJob response of the AWS Comprehend service. It contains the job details, not the classification results: Amazon Comprehend writes the results to the location you set in Output's S3 URI when the job completes.

Field	Description
sdkResponseMetadata	Metadata of the AWS response, such as the requestId.
sdkHttpMetadata	The HTTP status code and headers of the AWS response.
jobId	The identifier of the job.
jobArn	The ARN of the job.
jobStatus	The status of the job, for example SUBMITTED.
documentClassifierArn	The ARN of the document classifier that processes the job.

For example:

{
  "sdkResponseMetadata": {
    "requestId": "929bf054-193b-48e6-ab80-3aeeb613b415"
  },
  "sdkHttpMetadata": {
    "httpHeaders": { "Content-Type": "application/x-amz-json-1.1" },
    "httpStatusCode": 200,
    "allHttpHeaders": { "Content-Type": ["application/x-amz-json-1.1"] }
  },
  "jobId": "12345678-1234-1234-1234-123456789012",
  "jobArn": "arn:aws:comprehend:eu-central-1:123456789012:document-classification-job/12345678-1234-1234-1234-123456789012",
  "jobStatus": "SUBMITTED",
  "documentClassifierArn": "arn:aws:comprehend:eu-central-1:123456789012:document-classifier/my-classifier"
}

Troubleshooting

To learn about general error handling in Camunda, see BPMN errors and failing jobs.

Further resources

• Amazon Comprehend documentation