There are five connectors that can be used to invoke different Amazon Web Services (AWS):

• Lambda
• Comprehend
• Rekognition
• Textract
• Transcribe

All Amazon connectors are displayed on the process diagram with their respective AWS logos.

Important: All AWS connectors require an AWS account with permission to access the features provided by Amazon. This account is separate to the Alfresco hosted environment and should be created and managed by customers.

Lambda

The INVOKE action is used by the Lambda connector to invoke Amazon Web Services (AWS) Lambda functions.

The input parameters to invoke a Lambda function are:

The output parameters from invoking a Lambda function are:

Lambda configuration parameters

The configuration parameters for the Lambda connector are:

Lambda errors

The possible errors that can be handled by the Lambda connector are:

Comprehend

The Comprehend connector provides a standard mechanism to extract entities and Personally identifiable information (PII) entities from text in your documents. The ENTITY action is used by the Comprehend connector to execute Amazon Comprehend natural language processing (NLP) services and identify and analyze text from specific plain text files. The Comprehend connector supports default entity recognition, custom entity recognition, and custom document classification.

Note: The Comprehend connector can only receive either files or text but not both at the same time.

The Comprehend connector can extract entities and PII from the following file formats:

• text/plain
• application/x-tar
• /zip
• /vnd.ms-outlook
• /pdf (max size in bytes: 26214400)
• /msword
• /vnd.ms-project
• /vnd.ms-outlook
• /vnd.ms-powerpoint
• /vnd.visio
• /vnd.ms-excel
• /vnd.openxmlformats-officedocument.spreadsheetml.sheet
• /vnd.ms-word.document.macroenabled.12
• /vnd.openxmlformats-officedocument.wordprocessingml.document
• /vnd.ms-word.template.macroenabled.12
• /vnd.openxmlformats-officedocument.wordprocessingml.template
• /vnd.ms-powerpoint.template.macroenabled.12
• /vnd.openxmlformats-officedocument.presentationml.template
• /vnd.ms-powerpoint.addin.macroenabled.12
• /vnd.ms-powerpoint.slideshow.macroenabled.12
• /vnd.openxmlformats-officedocument.presentationml.slideshow
• /vnd.ms-powerpoint.presentation.macroenabled.12
• /vnd.openxmlformats-officedocument.presentationml.presentation
• /vnd.ms-powerpoint.slide.macroenabled.12
• /vnd.openxmlformats-officedocument.presentationml.slide
• /vnd.ms-excel.addin.macroenabled.12
• /vnd.ms-excel.sheet.binary.macroenabled.12
• /vnd.ms-excel.sheet.macroenabled.12
• /vnd.openxmlformats-officedocument.spreadsheetml.sheet
• /vnd.ms-excel.template.macroenabled.12
• /vnd.openxmlformats-officedocument.spreadsheetml.template
• /x-cpio
• /java-archive
• /x-netcdf
• /msword
• /vnd.ms-word.document.macroenabled.12
• /vnd.openxmlformats-officedocument.wordprocessingml.document
• /vnd.ms-word.template.macroenabled.12
• /vnd.openxmlformats-officedocument.wordprocessingml.template
• /x-gzip
• /x-hdf
• text/html
• /vnd.apple.keynote
• /vnd.ms-project
• /vnd.apple.numbers
• /vnd.oasis.opendocument.chart
• /vnd.oasis.opendocument.image
• /vnd.oasis.opendocument.text-master
• /vnd.oasis.opendocument.presentation
• /vnd.oasis.opendocument.spreadsheet
• /vnd.oasis.opendocument.text
• /ogg
• /vnd.oasis.opendocument.text-web
• /vnd.oasis.opendocument.presentation-template
• /vnd.oasis.opendocument.spreadsheet-template
• /vnd.oasis.opendocument.text-template
• /vnd.apple.pages
• /pdf "maxSourceSizeBytes": 26214400,
• /vnd.ms-powerpoint.template.macroenabled.12
• /vnd.openxmlformats-officedocument.presentationml.template
• /vnd.ms-powerpoint.addin.macroenabled.12
• /vnd.ms-powerpoint.slideshow.macroenabled.12
• /vnd.openxmlformats-officedocument.presentationml.slideshow
• /vnd.ms-powerpoint
• /vnd.ms-powerpoint.presentation.macroenabled.12
• /vnd.openxmlformats-officedocument.presentationml.presentation
• /x-rar-compressed
• /rss+xml
• /rtf
• /vnd.ms-powerpoint.slide.macroenabled.12
• /vnd.openxmlformats-officedocument.presentationml.slide
• /vnd.sun.xml.writer
• text/xml
• /vnd.visio
• /xhtml+xml
• /vnd.ms-excel.addin.macroenabled.12
• /vnd.ms-excel
• /vnd.ms-excel.sheet.binary.macroenabled.12
• /vnd.ms-excel.sheet.macroenabled.12
• /vnd.openxmlformats-officedocument.spreadsheetml.sheet
• /vnd.ms-excel.template.macroenabled.12
• /vnd.openxmlformats-officedocument.spreadsheetml.template
• /x-compress
• text/csv
• /msword

AWS Configuration

The Amazon Comprehend APIs that are called using the connector are:

• DetectDominantLanguage
• DetectEntities
• BatchDetectEntities
• StartEntitiesDetectionJob
• DescribeEntitiesDetectionJob
• DetectPiiEntities
• StartPiiEntitiesDetectionJob
• DescribePiiEntitiesDetectionJob
• StartDocumentClassificationJob

To perform these calls it uses the AWS Comprehend SDK. This requires IAM users with the correct permissions to be created. The easiest way to do this is to give an IAM user the AWS managed policy ComprehendFullAccess. If you want to be stricter with access rights see the list of all comprehend API permissions.

The Asynchronous calls also require the ability to read and write to an Amazon S3 bucket so the IAM user must have access to the configured bucket. As well as the IAM user accessing the data the Comprehend service itself requires access, for more see Role-Based Permissions Required for Asynchronous Operations .

To allow the library to use this IAM user when communicating with the Comprehend service an AWS access key and secret key must be available, for more see Using the Default Credential Provider Chain

DetectDominantLanguage

You need to supply the calls that detect the language of the text document that is going to be processed. To do this, the connector calls the DetectDominantLanguage API. The DetectDominantLanguage call only works on text smaller than a configurable limit, the default is 5000 bytes. The connector uses the first bytes/characters of the document to determine what language to use when making calls to AWS Comprehend to determine which language is being used.

The DetectDominantLanguage service currently supports a greater set of languages than the entity detection services. It does this by checking the returned language against a configurable list of available languages.

Note: Currently only EN and ES are supported by AWS entity detection. If the detected language is not in this list a configurable default language is used instead, which is EN by default.

Entities

The following are the different types of entities:

Depending on the size of the input the connector will process it in a different a way.

The DetectEntities operation will be called if the supplied text file is smaller than a configurable limit, by default 5000 bytes. If the input file is larger than this then a different API must be used.

The BatchDetectEntitie is used if the file is larger than the DetectEntities limit although it also has a configurable limit, by default 125000 bytes. When you use the Batch API call the input file is split into chunks of less than the configurable limit, by default 5000 bytes.

The StartEntitiesDetectionJob and DescribeEntititesDetectionJob are used if the input file is larger than the BatchDetectEntities limit, by default 5000 bytes. Similar to the batch approach, the input file will be divided into a set of smaller files of a certain configured size. When dividing the original file, the engine ensures that it only includes full words and does not split on a non whitespace character.

The divided files are then uploaded to Amazon S3 using the same key prefix for all files. When all of them have been uploaded an asynchronous entity detection job is started. This is then followed by a polling process to check the status of the job until it finishes or the timeout is reached.

If the asynchronous job finishes successfully a compressed output file (output.tar.gz) with the result will be written by Amazon Comprehend. The file will be saved to the same bucket within a directory that is using the same key prefix. For more see Asynchronous Batch Processing . The output file is downloaded from Amazon S3 and parsed into a BatchDetectEntitiesResult object. At the end of the process, all the resource files are cleaned, both locally and at Amazon S3.

PII Entities

Depending on the size of the input the connector will process it in a different way.

The DetectPiiEntities operation will be called if the supplied text file is smaller than a configurable limit, by default 5000 bytes. If the input file is larger than this then a different API must be used.

The StartPiiEntitiesDetectionJob and DescribePiiEntitiesDetectionJob are used if the input file is larger than the AsynchDetectPIIEntities limit, by default 5000 bytes. The input file will be divided into a set of smaller files of a certain configured size. When dividing the original file, the engine ensures that it only includes full words and will not split on a non whitespace character.

The divided files are then uploaded to Amazon S3 using the same key prefix for all files. When all of them have been uploaded an asynchronous entity detection job is started. This is then followed by a polling process to check the status of the job until it finishes or the timeout is reached.

If the asynchronous job finishes successfully a compressed output file (output.tar.gz) with the result will be written by Amazon Comprehend. The file will be saved to the same bucket within a directory that is using the same key prefix. For more see Asynchronous Batch Processing . The output file is downloaded from Amazon S3 and parsed into a BatchDetectPiiResult object. At the end of the process, all the resource files are cleaned, both locally and at Amazon S3.

The StartDocumentClassificationJob operation is always performed asynchronously. It requires a custom model and the classifier ARN must be provided. You can provide the custom classification ARN in two ways:

1. Use the AWS_COMPREHEND_CUSTOM_CLASSIFICATION_ARN environment variable when deploying the application.

2. Use the customClassificationArn input variable in the connector action. If the variable is not provided the AWS_COMPREHEND_CUSTOM_CLASSIFICATION_ARN value is used.

BPMN Tasks Configuration

The following describes an example of how the text analysis connector is setup in AAE:

As part of the BPMN definition process, any service task responsible for triggering the text analysis comprehend.ENTITY has to be set as the value for its implementation attribute.

The following variables must be configured for the text analysis to function.

The input parameters of Entity detection are:

Note: The connector must receive either files or text but not both at the same time.

The following is an example of the POST body for the Activiti REST API http:////rb/v1/process-instances endpoint:

Code copied to clipboard.
{
  "processDefinitionKey": "TextAnalysisProcessTest",
  "processInstanceName": "processTextAnalysisTest_Simple",
  "businessKey": "MyBusinessKey",
  "variables": {
    "file" : [
        {
            "nodeId":"ad844189-9afb-4afb-965b-380db73022aa"
    	}
    ],
  	"maxEntities" : 50,
  	"confidenceLevel" : "0.95",
	"timeout" : 10000
  },
  "payloadType":"StartProcessPayload"
}

In the business process definition, the text analysis service task called textAnalysisTask has the implementation attribute configured to use the connector.

Code copied to clipboard.
<bpmn2:serviceTask id="ServiceTask_0j2v2yc" name="textAnalysisTask" implementation="comprehend.ENTITY">
  <bpmn2:incoming>SequenceFlow_0kibr65</bpmn2:incoming>
  <bpmn2:outgoing>SequenceFlow_1048knn</bpmn2:outgoing>
</bpmn2:serviceTask>

The input parameters of PII Entity detection are:

Note: The connector must receive either files or text but not both at the same time.

The input parameters of Document classification are:

Note: The connector must receive either files or text but not both at the same time.

The output parameters from the entity detection are:

The output parameters from the PII entity detection are:

The output parameters from the Document classification are:

Comprehend configuration parameters

The configuration parameters for the Comprehend connector are:

Comprehend errors

The possible errors that can be handled by the Comprehend connector are:

Limitations

PDF files larger than 26214400 bytes are not supported.

Rekognition

The LABEL action is used by the Rekognition connector to execute Amazon Rekognition services to identify and label the objects in JPEG and PNG files that are less than 15mb in size.

The Amazon Rekognition API that is called is the Detect Labels API.

Files between 5mb and 15mb are uploaded to an Amazon S3 bucket before processing. The IAM user configured to run the Rekognition service requires access to this bucket, the Rekognition service itself and to have the rekognition:DetectLabels permission.

The input parameters of the Rekognition connector are:

The output parameters from the Rekognition analysis are:

Rekognition configuration parameters

The configuration parameters for the Rekognition connector are:

Rekognition errors

The possible errors that can be handled by the Rekognition connector are:

Textract

The EXTRACT action is used by the Textract connector to execute Amazon Textract to extract text and metadata from JPEG and PNG files that are less than 5mb in size.

The Amazon Textract APIs called are the Detect Document Text API which joins all LINE block objects with a line separator between them and the Analyze Document API with FORM and TABLES analysis.

The IAM user configured to run the Textract services needs to have the textract:DetectDocumentText and textract:AnalyzeDocument permissions.

The input parameters of the Textract connector are:

The output parameters from the Textract analysis are:

Textract configuration parameters

The configuration parameters for the Textract connector are:

Textract errors

The possible errors that can be handled by the Textract connector are:

Transcribe

The transcribe connector provides a standard mechanism to obtain speech to text information from audio and video files using Amazon Transcribe.

Installation

The connector is a Spring Boot application that is included as a separate service of your AAE deployment.

AWS Configuration

Alfresco recommends you access AWS using AWS Identity and Access Management (IAM). To use IAM to access AWS, create an IAM user, add the user to an IAM group with administrative permissions, and then grant administrative permissions to the IAM user. You can then access AWS using a special URL and the IAM user’s credentials.

BPMN Tasks Configuration

As part of BPMN definition process, any service task responsible for triggering speech to text needs to set transcribe.TRANSCRIBE as the value for its implementation attribute.

In addition to the above configuration, these variables are required to perform the audio analysis:

The input parameters of the transcribe connector are:

The output parameters of the Transcribe connector are:

Transcribe configuration parameters

The configuration parameters for the Transcribe connector are:

Transcribe errors

The possible errors that can be handled by the Transcribe connector are:

Limitations

Minimum confidence is not currently supported. The confidence is however included as part of the response.