```
**Example of an automated classification template.**
To automate this simple text classification sample, include the Liquid tag `{{ task.input.source }}`. This example uses the [crowd-classifier](sms-ui-template-crowd-classifier.md) element.
## Preview a Worker Task Template
To preview a custom worker task template, use the SageMaker AI `RenderUiTemplate` operation. You can use the `RenderUiTemplate` operation with the Amazon CLI or your preferred Amazon SDK. For documentation on the supported language specific SDKs for this API operation, see the [https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_RenderUiTemplate.html#API_RenderUiTemplate_SeeAlso](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_RenderUiTemplate.html#API_RenderUiTemplate_SeeAlso) section of the [https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_RenderUiTemplate.html](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_RenderUiTemplate.html).
**Prerequisites**
To preview your worker task template, the Amazon Identity and Access Management (IAM) role Amazon Resource Name (ARN), or `RoleArn`, that you use must have permission to access to the S3 objects that are used by the template. To learn how to configure your role or user see [Enable Worker Task Template Previews](a2i-permissions-security.md#permissions-for-worker-task-templates-augmented-ai).
**To preview your worker task template using the `RenderUiTemplate` operation:**
1. Provide a **`RoleArn`** of the role with required policies attached to preview your custom template.
1. In the **`Input`** parameter of **`Task`**, provide a JSON object that contains values for the variables defined in the template. These are the variables that are substituted for the `task.input.source` variable. For example, if you define a task.input.text variable in your template, you can supply the variable in the JSON object as `text`: `sample text`.
1. In the **`Content`** parameter of **`UiTemplate`**, insert your template.
Once you've configured `RenderUiTemplate`, use your preferred SDK or the Amazon CLI to submit a request to render your template. If your request was successful, the response includes [https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_RenderUiTemplate.html#API_RenderUiTemplate_ResponseSyntax](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_RenderUiTemplate.html#API_RenderUiTemplate_ResponseSyntax), a Liquid template that renders the HTML for the worker UI.
**Important**
To preview your template, you need an IAM role with permissions to read Amazon S3 objects that get rendered on your user interface. For a sample policy that you can attach to your IAM role to grant these permissions, see [Enable Worker Task Template Previews](a2i-permissions-security.md#permissions-for-worker-task-templates-augmented-ai).
# Creating Good Worker Instructions
Creating good instructions for your human review jobs improves your worker's accuracy in completing their task. You can modify the default instructions that are provided in the console when creating a human review workflow, or you can use the console to create a custom worker template and include your instructions in this template. The instructions are shown to the worker on the UI page where they complete their labeling task.
## Create Good Worker Instructions
There are three kinds of instructions in the Amazon Augmented AI console:
+ **Task Description** – The description should provide a succinct explanation of the task.
+ **Instructions** – These instructions are shown on the same webpage where workers complete a task. These instructions should provide an easy reference to show the worker the correct way to complete the task.
+ **Additional Instructions** – These instructions are shown in a dialog box that appears when a worker chooses **View full instructions**. We recommend that you provide detailed instructions for completing the task, and include several examples showing edge cases and other difficult situations for labeling objects.
## Add Example Images to Your Instructions
Images provide useful examples for your workers. To add a publicly accessible image to your instructions, do the following:
1. Place the cursor where the image should go in the instructions editor.
1. Choose the image icon in the editor toolbar.
1. Enter the URL of your image.
If your instruction image is in an S3 bucket that isn't publicly accessible, do the following:
+ For the image URL, enter: `{{ 'https://s3.amazonaws.com/your-bucket-name/image-file-name' | grant_read_access }}`.
This renders the image URL with a short-lived, one-time access code that's appended so the worker's browser can display it. A broken image icon is displayed in the instructions editor, but previewing the tool displays the image in the rendered preview. See [s3\$1presigngrant\$1read\$1accesss3\$1presign](a2i-custom-templates.md#a2i-custom-templates-step2-automate-grantreadaccess) for more information about the `grand_read_access` element.
# Monitor and Manage Your Human Loop
Once you've started a human review loop, you can check the results of tasks sent to the loop and manage it using the [Amazon Augmented AI Runtime API](https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/Welcome.html). Additionally, Amazon A2I integrates with Amazon EventBridge (also known as Amazon CloudWatch Events) to alert you when a human review loop status changes to `Completed`, `Failed`, or `Stopped`. This event delivery is guaranteed at least once, which means all events created when human loops finish are successfully delivered to EventBridge.
Use the procedures below to learn how to use the Amazon A2I Runtime API to monitor and manage your human loops. See [Use Amazon CloudWatch Events in Amazon Augmented AI](a2i-cloudwatch-events.md) to learn how Amazon A2I integrates with Amazon EventBridge.
**To check your output data:**
1. Check the results of your human loop by calling the [https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_DescribeHumanLoop.html](https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_DescribeHumanLoop.html) operation. The result of this API operation contains information about the reason for and outcome of the loop activation.
1. Check the output data from your human loop in Amazon Simple Storage Service (Amazon S3). In the path to the data, `YYYY/MM/DD/hh/mm/ss` represents the human loop creation date with year (`YYYY`), month (`MM`), and day (`DD`), and the creation time with hour (`hh`), minute (`mm`), and second (`ss`).
```
s3://customer-output-bucket-specified-in-flow-definition/flow-definition-name/YYYY/MM/DD/hh/mm/ss/human-loop-name/output.json
```
You can integrate this structure with Amazon Glue or Amazon Athena to partition and analyze your output data. For more information, see [Managing Partitions for ETL Output in Amazon Glue](https://docs.amazonaws.cn/glue/latest/dg/aws-glue-programming-etl-partitions.html).
To learn more about Amazon A2I output data format, see [Amazon A2I Output Data](a2i-output-data.md).
**To stop and delete your human loop:**
1. Once a human loop has been started, you can stop your human loop by calling the [https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_StopHumanLoop.html](https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_StopHumanLoop.html) operation using the `HumanLoopName`. If a human loop was successfully stopped, the server sends back an HTTP 200 response.
1. To delete a human loop for which the status equals `Failed`, `Completed`, or `Stopped`, use the [https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_DeleteHumanLoop.html](https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_DeleteHumanLoop.html) operation.
**To list human loops:**
1. You can list all active human loops by calling the [https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_ListHumanLoops.html](https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_ListHumanLoops.html) operation. You can filter human loops by the creation date of the loop using the `CreationTimeAfter` and `CreateTimeBefore` parameters.
1. If successful, `ListHumanLoops` returns [https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_HumanLoopSummary.html](https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_HumanLoopSummary.html) and `NextToken` objects in the response element. `HumanLoopSummaries` contains information about a single human loop. For example, it lists a loop's status and, if applicable, its failure reason.
Use the string returned in `NextToken` as an input in a subsequent call to `ListHumanLoops` to see the next page of human loops.
# Amazon A2I Output Data
Output Data
When your machine learning workflow sends Amazon A2I a data object, a *human loop* is created and human reviewers receive a *task* to review that data object. The output data from each human review task is stored in the Amazon Simple Storage Service (Amazon S3) output bucket you specify in your human review workflow. In the path to the data, `YYYY/MM/DD/hh/mm/ss` represents the human loop creation date with year (`YYYY`), month (`MM`), and day (`DD`), and the creation time with hour (`hh`), minute (`mm`), and second (`ss`).
```
s3://customer-output-bucket-specified-in-flow-definition/flow-definition-name/YYYY/MM/DD/hh/mm/ss/human-loop-name/output.json
```
The content of your output data depends on the type of [task type](https://docs.amazonaws.cn/sagemaker/latest/dg/a2i-task-types-general.html) (built-in or custom) and the type of [workforce](https://docs.amazonaws.cn/sagemaker/latest/dg/sms-workforce-management.html) you use. Your output data always includes the response from the human worker. Additionally, output data may include metadata about the human loop, the human reviewer (worker), and the data object.
Use the following sections to learn more about Amazon A2I output data format for different task types and workforces.
## Output Data From Built-In Task Types
Amazon A2I built-in task types include Amazon Textract and Amazon Rekognition. In addition to human responses, the output data from one of these tasks includes details about the reason the human loop was created and information about the integrated service used to create the human loop. Use the following table to learn more about the output data schema for all built-in task types. The *value* for each of these parameters depends on the service you use with Amazon A2I. Refer to the second table in this section for more information about these service-specific values.
****
| Parameter | Value Type | Example Values | Description |
| --- | --- | --- | --- |
| awsManagedHumanLoopRequestSource | String | AWS/Rekognition/DetectModerationLabels/Image/V3 or AWS/Textract/AnalyzeDocument/Forms/V1 | The API operation and associated Amazon services that requested that Amazon A2I create the a human loop. This is the API operation you use to configure your Amazon A2I human loop. |
| flowDefinitionArn | String | arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name | The Amazon Resource Number (ARN) of the human review workflow (flow definition) used to create the human loop. |
| humanAnswers | List of JSON objects | {
"answerContent": {
"AWS/Rekognition/DetectModerationLabels/Image/V3": {
"moderationLabels": [...]
}
}, or{
"answerContent": {
"AWS/Textract/AnalyzeDocument/Forms/V1": {
"blocks": [...]
}
}, | A list of JSON objects that contain worker responses in answerContent. This object also contains submission details and, if a private workforce was used, worker metadata. To learn more, see [Track Worker Activity](#a2i-worker-id-private). For human loop output data produced from Amazon Rekognition `DetectModerationLabel` review tasks, this parameter only contains positive responses. For example, if workers select *No content*, this response is not included. |
| humanLoopName | String | `'human-loop-name'` | The name of the human loop. |
| inputContent | JSON object | {
"aiServiceRequest": {...},
"aiServiceResponse": {...},
"humanTaskActivationConditionResults": {...},
"selectedAiServiceResponse": {...}
} | The input content the Amazon service sent to Amazon A2I when it requested a human loop be created. |
| aiServiceRequest | JSON object | {
"document": {...},
"featureTypes": [...],
"humanLoopConfig": {...}
}or {
"image": {...},
"humanLoopConfig": {...}
} | The original request sent to the Amazon service integrated with Amazon A2I. For example, if you use Amazon Rekognition with Amazon A2I, this includes the request made through the API operation `DetectModerationLabels`. For Amazon Textract integrations, this includes the request made through `AnalyzeDocument`. |
| aiServiceResponse | JSON object | {
"moderationLabels": [...],
"moderationModelVersion": "3.0"
} or {
"blocks": [...],
"documentMetadata": {}
} | The full response from the Amazon service. This is the data that is used to determine if a human review is required. This object may contain metadata about the data object that is not shared with human reviewers. |
| selectedAiServiceResponse | JSON object | {
"moderationLabels": [...],
"moderationModelVersion": "3.0"
} or {
"blocks": [...],
"documentMetadata": {}
} | The subset of the `aiServiceResponse` that matches the activation conditions in `ActivationConditions`. All data objects listed in `aiServiceResponse` are listed in `selectedAiServiceResponse` when inferences are randomly sampled, or all inferences initiated activation conditions. |
| humanTaskActivationConditionResults | JSON object | {
"Conditions": [...]
} | A JSON object in `inputContent` that contains the reason a human loop was created. This includes a list of the activation conditions (`Conditions`) included in your human review workflow (flow definition), and the evaluation result for each condition–this result is either `true` or `false`. To learn more about activation conditions, see [JSON Schema for Human Loop Activation Conditions in Amazon Augmented AI](a2i-human-fallback-conditions-json-schema.md). |
Select a tab on the following table to learn about the task type–specific parameters and see an example output-data code block for each of the built-in task types.
------
#### [ Amazon Textract Task Type Output Data ]
When you use the Amazon Textract built-in integration, you see `'AWS/Textract/AnalyzeDocument/Forms/V1'` as the value for `awsManagedHumanLoopRequestSource` in your output data.
The `answerContent` parameter contains a `Block` object that includes human responses for all blocks sent to Amazon A2I.
The `aiServiceResponse` parameter also includes a `Block` object with Amazon Textract's response to the original request sent using to `AnalyzeDocument`.
To learn more about the parameters you see in the block object, refer to [Block](https://docs.amazonaws.cn/textract/latest/dg/API_Block.html) in the *Amazon Textract Developer Guide*.
The following is an example of the output data from an Amazon A2I human review of Amazon Textract document analysis inferences.
```
{
"awsManagedHumanLoopRequestSource": "AWS/Textract/AnalyzeDocument/Forms/V1",
"flowDefinitionArn": "arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name",
"humanAnswers": [
{
"answerContent": {
"AWS/Textract/AnalyzeDocument/Forms/V1": {
"blocks": [...]
}
},
"submissionTime": "2020-09-28T19:17:59.880Z",
"workerId": "111122223333",
"workerMetadata": {
"identityData": {
"identityProviderType": "Cognito",
"issuer": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_111111",
"sub": "c6aa8eb7-9944-42e9-a6b9-111122223333"
}
}
}
],
"humanLoopName": "humnan-loop-name",
"inputContent": {
"aiServiceRequest": {
"document": {
"s3Object": {
"bucket": "amzn-s3-demo-bucket1",
"name": "document-demo.jpg"
}
},
"featureTypes": [
"TABLES",
"FORMS"
],
"humanLoopConfig": {
"dataAttributes": {
"contentClassifiers": [
"FreeOfPersonallyIdentifiableInformation"
]
},
"flowDefinitionArn": "arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name",
"humanLoopName": "humnan-loop-name"
}
},
"aiServiceResponse": {
"blocks": [...],
"documentMetadata": {
"pages": 1
}
},
"humanTaskActivationConditionResults": {
"Conditions": [
{
"EvaluationResult": true,
"Or": [
{
"ConditionParameters": {
"ImportantFormKey": "Mail address",
"ImportantFormKeyAliases": [
"Mail Address:",
"Mail address:",
"Mailing Add:",
"Mailing Addresses"
],
"KeyValueBlockConfidenceLessThan": 100,
"WordBlockConfidenceLessThan": 100
},
"ConditionType": "ImportantFormKeyConfidenceCheck",
"EvaluationResult": true
},
{
"ConditionParameters": {
"ImportantFormKey": "Mail address",
"ImportantFormKeyAliases": [
"Mail Address:",
"Mail address:",
"Mailing Add:",
"Mailing Addresses"
]
},
"ConditionType": "MissingImportantFormKey",
"EvaluationResult": false
}
]
}
]
},
"selectedAiServiceResponse": {
"blocks": [...]
}
}
}
```
------
#### [ Amazon Rekognition Task Type Output Data ]
When you use the Amazon Textract built-in integration, you see the string `'AWS/Rekognition/DetectModerationLabels/Image/V3'` as the value for `awsManagedHumanLoopRequestSource` in your output data.
The `answerContent` parameter contains a `moderationLabels` object that contains human responses for all moderation labels sent to Amazon A2I.
The `aiServiceResponse` parameter also includes a `moderationLabels` object with Amazon Rekognition's response to the original request sent to `DetectModerationLabels`.
To learn more about the parameters you see in the block object, refer to [ModerationLabel](https://docs.amazonaws.cn/rekognition/latest/dg/API_ModerationLabel.html) in the Amazon Rekognition Developer Guide.
The following is an example of the output data from an Amazon A2I human review of Amazon Rekognition image moderation inferences.
```
{
"awsManagedHumanLoopRequestSource": "AWS/Rekognition/DetectModerationLabels/Image/V3",
"flowDefinitionArn": "arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name",
"humanAnswers": [
{
"answerContent": {
"AWS/Rekognition/DetectModerationLabels/Image/V3": {
"moderationLabels": [...]
}
},
"submissionTime": "2020-09-28T19:22:35.508Z",
"workerId": "ef7294f850a3d9d1",
"workerMetadata": {
"identityData": {
"identityProviderType": "Cognito",
"issuer": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_111111",
"sub": "c6aa8eb7-9944-42e9-a6b9-111122223333"
}
}
}
],
"humanLoopName": "humnan-loop-name",
"inputContent": {
"aiServiceRequest": {
"humanLoopConfig": {
"flowDefinitionArn": "arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name",
"humanLoopName": "humnan-loop-name"
},
"image": {
"s3Object": {
"bucket": "amzn-s3-demo-bucket1",
"name": "example-image.jpg"
}
}
},
"aiServiceResponse": {
"moderationLabels": [...],
"moderationModelVersion": "3.0"
},
"humanTaskActivationConditionResults": {
"Conditions": [
{
"EvaluationResult": true,
"Or": [
{
"ConditionParameters": {
"ConfidenceLessThan": 98,
"ModerationLabelName": "Suggestive"
},
"ConditionType": "ModerationLabelConfidenceCheck",
"EvaluationResult": true
},
{
"ConditionParameters": {
"ConfidenceGreaterThan": 98,
"ModerationLabelName": "Female Swimwear Or Underwear"
},
"ConditionType": "ModerationLabelConfidenceCheck",
"EvaluationResult": false
}
]
}
]
},
"selectedAiServiceResponse": {
"moderationLabels": [
{
"confidence": 96.7122802734375,
"name": "Suggestive",
"parentName": ""
}
],
"moderationModelVersion": "3.0"
}
}
}
```
------
## Output Data From Custom Task Types
When you add Amazon A2I to a custom human review workflow, you see the following parameters in the output data returned from human review tasks.
****
| Parameter | Value Type | Description |
| --- | --- | --- |
| `flowDefinitionArn` | String | The Amazon Resource Number (ARN) of the human review workflow (flow definition) used to create the human loop. |
| `humanAnswers` | List of JSON objects | A list of JSON objects that contain worker responses in answerContent. The value in this parameter is determined by the output received from your [worker task template](https://docs.amazonaws.cn/sagemaker/latest/dg/a2i-instructions-overview.html). If you are using a private workforce, worker metadata is included. To learn more, see [Track Worker Activity](#a2i-worker-id-private). |
| `humanLoopName` | String | The name of the human loop. |
| `inputContent` | JSON Object | The input content sent to Amazon A2I in the request to [https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_StartHumanLoop.html](https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_StartHumanLoop.html). |
The following is an example of output data from a custom integration with Amazon A2I and Amazon Transcribe. In this example, the `inputContent` consists of:
+ A path to an .mp4 file in Amazon S3 and the video title
+ The transcription returned from Amazon Transcribe (parsed from Amazon Transcribe output data)
+ A start and end time used by the worker task template to clip the .mp4 file and show workers a relevant portion of the video
```
{
"flowDefinitionArn": "arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name",
"humanAnswers": [
{
"answerContent": {
"transcription": "use lambda to turn your notebook"
},
"submissionTime": "2020-06-18T17:08:26.246Z",
"workerId": "ef7294f850a3d9d1",
"workerMetadata": {
"identityData": {
"identityProviderType": "Cognito",
"issuer": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_111111",
"sub": "c6aa8eb7-9944-42e9-a6b9-111122223333"
}
}
}
],
"humanLoopName": "human-loop-name",
"inputContent": {
"audioPath": "s3://amzn-s3-demo-bucket1/a2i_transcribe_demo/Fully-Managed Notebook Instances with Amazon SageMaker - a Deep Dive.mp4",
"end_time": 950.27,
"original_words": "but definitely use Lambda to turn your ",
"start_time": 948.51,
"video_title": "Fully-Managed Notebook Instances with Amazon SageMaker - a Deep Dive.mp4"
}
}
```
## Track Worker Activity
Amazon A2I provides information that you can use to track individual workers in task output data. To identify the worker that worked on the human review task, use the following from the output data in Amazon S3:
+ The `acceptanceTime` is the time that the worker accepted the task. The format of this date and time stamp is `YYYY-MM-DDTHH:MM:SS.mmmZ` for the year (`YYYY`), month (`MM`), day (`DD`), hour (`HH`), minute (`MM`), second (`SS`), and millisecond (`mmm`). The date and time are separated by a **T**.
+ The `submissionTime` is the time that the worker submitted their annotations using the **Submit** button. The format of this date and time stamp is `YYYY-MM-DDTHH:MM:SS.mmmZ` for the year (`YYYY`), month (`MM`), day (`DD`), hour (`HH`), minute (`MM`), second (`SS`), and millisecond (`mmm`). The date and time are separated by a **T**.
+ `timeSpentInSeconds` reports the total time, in seconds, that a worker actively worked on that task. This metric does not include time when a worker paused or took a break.
+ The `workerId` is unique to each worker.
+ If you use a [private workforce](https://docs.amazonaws.cn/sagemaker/latest/dg/sms-workforce-private.html), in `workerMetadata`, you see the following.
+ The `identityProviderType` is the service used to manage the private workforce.
+ The `issuer` is the Amazon Cognito user pool or OpenID Connect (OIDC) Identity Provider (IdP) issuer associated with the work team assigned to this human review task.
+ A unique `sub` identifier refers to the worker. If you create a workforce using Amazon Cognito, you can retrieve details about this worker (such as the name or user name) associated with this ID using Amazon Cognito. To learn how, see [Managing and Searching for User Accounts](https://docs.amazonaws.cn/cognito/latest/developerguide/how-to-manage-user-accounts.html#manage-user-accounts-searching-user-attributes) in *[Amazon Cognito Developer Guide](https://docs.amazonaws.cn/cognito/latest/developerguide/)*.
The following is an example of the output you may see if you use Amazon Cognito to create a private workforce. This is identified in the `identityProviderType`.
```
"submissionTime": "2020-12-28T18:59:58.321Z",
"acceptanceTime": "2020-12-28T18:59:15.191Z",
"timeSpentInSeconds": 40.543,
"workerId": "a12b3cdefg4h5i67",
"workerMetadata": {
"identityData": {
"identityProviderType": "Cognito",
"issuer": "https://cognito-idp.aws-region.amazonaws.com/aws-region_123456789",
"sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
}
}
```
The following is an example of the output you may see if you use your own OIDC IdP to create a private workforce:
```
"workerMetadata": {
"identityData": {
"identityProviderType": "Oidc",
"issuer": "https://example-oidc-ipd.com/adfs",
"sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
}
}
```
To learn more about using private workforces, see [Private workforce](sms-workforce-private.md).
# Permissions and Security in Amazon Augmented AI
Permissions and Security
When using Amazon Augmented AI (Amazon A2I) to create a human review workflow for your ML/AI application, you create and configure *resources* in Amazon SageMaker AI such as a human workforce and worker task templates. To configure and start a human loop, you either integrate Amazon A2I with other Amazon services such as Amazon Textract or Amazon Rekognition, or use the Amazon Augmented AI Runtime API. To create a human review workflow and start a human loop, you must attach certain policies to your Amazon Identity and Access Management (IAM) role or user. Specifically:
+ When you start a human loop using image input data on or after January 12th, 2020, you must add a CORS header policy to the Amazon S3 bucket that contains your input data. See [CORS Permission Requirement](#a2i-cors-update) to learn more.
+ When you create a flow definition, you need to provide a role that grants Amazon A2I permission to access Amazon S3 both for reading objects that are rendered in a human task UI and for writing the results of the human review.
This role must also have a trust policy attached to give SageMaker AI permission to assume the role. This allows Amazon A2I to perform actions in accordance with permissions that you attach to the role.
See [Add Permissions to the IAM Role Used to Create a Flow Definition](#a2i-human-review-permissions-s3) for example policies that you can modify and attach to the role you use to create a flow definition. These are the policies that are attached to the IAM role that is created in the **Human review workflows** section of the Amazon A2I area of the SageMaker AI console.
+ To create and start human loops, you either use an API operation from a built-in task type (such as `DetectModerationLabel` or `AnalyzeDocument`) or the Amazon A2I Runtime API operation `StartHumanLoop` in a custom ML application. You need to attach the `AmazonAugmentedAIFullAccess` managed policy to the user that invokes these API operations to grant permission to these services to use Amazon A2I operations. To learn how, see [Create a User That Can Invoke Amazon A2I API Operations](#create-user-grants).
This policy does *not* grant permission to invoke the API operations of the Amazon service associated with built-in task types. For example, `AmazonAugmentedAIFullAccess` does not grant permission to call the Amazon Rekognition `DetectModerationLabel` API operation or Amazon Textract `AnalyzeDocument` API operation. You can use the more general policy, `AmazonAugmentedAIIntegratedAPIAccess`, to grant these permissions. For more information, see [Create a User With Permissions to Invoke Amazon A2I, Amazon Textract, and Amazon Rekognition API Operations](#a2i-grant-general-permission). This is a good option when you want to grant a user broad permissions to use Amazon A2I and integrated Amazon services' API operations.
If you want to configure more granular permissions, see [Amazon Rekognition Identity-Based Policy Examples](https://docs.amazonaws.cn/rekognition/latest/dg/security_iam_id-based-policy-examples.html) and [Amazon Textract Identity-Based Policy Examples](https://docs.amazonaws.cn/textract/latest/dg/security_iam_id-based-policy-examples.html) for identity-based policies you can use to grant permission to use these individual services.
+ To preview your custom worker task UI template, you need an IAM role with permissions to read Amazon S3 objects that get rendered on your user interface. See a policy example in [Enable Worker Task Template Previews](#permissions-for-worker-task-templates-augmented-ai).
**Topics**
+ [
## CORS Permission Requirement
](#a2i-cors-update)
+ [
## Add Permissions to the IAM Role Used to Create a Flow Definition
](#a2i-human-review-permissions-s3)
+ [
## Create a User That Can Invoke Amazon A2I API Operations
](#create-user-grants)
+ [
## Create a User With Permissions to Invoke Amazon A2I, Amazon Textract, and Amazon Rekognition API Operations
](#a2i-grant-general-permission)
+ [
## Enable Worker Task Template Previews
](#permissions-for-worker-task-templates-augmented-ai)
+ [
## Using Amazon A2I with Amazon KMS Encrypted Buckets
](#a2i-kms-encryption)
+ [
## Additional Permissions and Security Resources
](#additional-security-resources-augmented-ai)
## CORS Permission Requirement
Earlier in 2020, widely used browsers like Chrome and Firefox changed their default behavior for rotating images based on image metadata, referred to as [EXIF data](https://en.wikipedia.org/wiki/Exif). Previously, images would always display in browsers exactly how they are stored on disk, which is typically unrotated. After the change, images now rotate according to a piece of image metadata called *orientation value*. This has important implications for the entire machine learning (ML) community. For example, if the EXIF orientation is not considered, applications that are used to annotate images may display images in unexpected orientations and result in incorrect labels.
Starting with Chrome 89, Amazon can no longer automatically prevent the rotation of images because the web standards group W3C has decided that the ability to control rotation of images violates the web’s Same-Origin Policy. Therefore, to ensure human workers annotate your input images in a predictable orientation when you submit requests to create a human loop, you must add a CORS header policy to the S3 buckets that contain your input images.
**Important**
If you do not add a CORS configuration to the S3 buckets that contains your input data, human review tasks for those input data objects fail.
You can add a CORS policy to an S3 bucket that contains input data in the Amazon S3 console. To set the required CORS headers on the S3 bucket that contains your input images in the S3 console, follow the directions detailed in [How do I add cross-domain resource sharing with CORS?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/add-cors-configuration.html). Use the following CORS configuration code for the buckets that host your images. If you use the Amazon S3 console to add the policy to your bucket, you must use the JSON format.
**JSON**
```
[{
"AllowedHeaders": [],
"AllowedMethods": ["GET"],
"AllowedOrigins": ["*"],
"ExposeHeaders": []
}]
```
**XML**
```
*
GET
```
The following GIF demonstrates the instructions found in the Amazon S3 documentation to add a CORS header policy using the Amazon S3 console.
![\[Gif on how to add a CORS header policy using the Amazon S3 console.\]](http://docs.amazonaws.cn/en_us/sagemaker/latest/dg/images/sms/gifs/cors-config.gif)
## Add Permissions to the IAM Role Used to Create a Flow Definition
To create a flow definition, attach the policies in this section to the role that you use when creating a human review workflow in the SageMaker AI console, or when using the `CreateFlowDefinition` API operation.
+ If you are using the console to create a human review workflow, enter the role Amazon Resource Name (ARN) in the **IAM role** field when [creating a human review workflow in the console](https://docs.amazonaws.cn/sagemaker/latest/dg/create-human-review-console.html).
+ When creating a flow definition using the API, attach these policies to the role that is passed to the `RoleArn` parameter of the `CreateFlowDefinition` operation.
When you create a human review workflow (flow definition), Amazon A2I invokes Amazon S3 to complete your task. To grant Amazon A2I permission to retrieve and store your files in your Amazon S3 bucket, create the following policy and attach it to your role. For example, if the images, documents, and other files that you are sending for human review are stored in an S3 bucket named `my_input_bucket`, and if you want the human reviews to be stored in a bucket named `my_output_bucket`, create the following policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws-cn:s3:::my_input_bucket/*"
]
},
{
"Effect": "Allow",
"Action": [
"s3:PutObject"
],
"Resource": [
"arn:aws-cn:s3:::my_output_bucket/*"
]
}
]
}
```
------
In addition, the IAM role must have the following trust policy to give SageMaker AI permission to assume the role. To learn more about IAM trust policies, see [Resource-Based Policies](https://docs.amazonaws.cn/IAM/latest/UserGuide/access_policies.html#policies_resource-based) section of **Policies and Permissions** in the *Amazon Identity and Access Management* documentation.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowSageMakerToAssumeRole",
"Effect": "Allow",
"Principal": {
"Service": "sagemaker.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
For more information about creating and managing IAM roles and policies, see the following topics in the *Amazon Identity and Access Management User Guide*:
+ To create an IAM role, see [Creating a Role to Delegate Permissions to an IAM User](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles_create_for-user.html).
+ To learn how to create IAM policies, see [Creating IAM Policies](https://docs.amazonaws.cn/IAM/latest/UserGuide/access_policies_create.html).
+ To learn how to attach an IAM policy to a role, see [Adding and Removing IAM Identity Permissions](https://docs.amazonaws.cn/IAM/latest/UserGuide/access_policies_manage-attach-detach.html).
## Create a User That Can Invoke Amazon A2I API Operations
To use Amazon A2I to create and start human loops for Amazon Rekognition, Amazon Textract, or the Amazon A2I runtime API, you must use a user that has permissions to invoke Amazon A2I operations. To do this, use the IAM console to attach the [https://console.amazonaws.cn/iam/home?region=us-east-2#/policies/arn:aws:iam::aws:policy/AmazonAugmentedAIFullAccess$jsonEditor](https://console.amazonaws.cn/iam/home?region=us-east-2#/policies/arn:aws:iam::aws:policy/AmazonAugmentedAIFullAccess$jsonEditor) managed policy to a new or existing user.
This policy grants permission to a user to invoke API operations from the SageMaker API for flow definition creation and management and the Amazon Augmented AI Runtime API for human loop creation and management. To learn more about these API operations, see [Use APIs in Amazon Augmented AI](https://docs.amazonaws.cn/sagemaker/latest/dg/a2i-api-references.html).
`AmazonAugmentedAIFullAccess` does not grant permissions to use Amazon Rekognition or Amazon Textract API operations.
**Note**
You can also attach the `AmazonAugmentedAIFullAccess` policy to an IAM role that is used to create and start a human loop.
To provide access, add permissions to your users, groups, or roles:
+ Users managed in IAM through an identity provider:
Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*.
+ IAM users:
+ Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*.
+ (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*.
For more information, see [Adding and Removing IAM Identity Permissions](https://docs.amazonaws.cn/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) in the *Amazon Identity and Access Management User Guide*.
## Create a User With Permissions to Invoke Amazon A2I, Amazon Textract, and Amazon Rekognition API Operations
To create a user that has permission to invoke the API operations used by the built-in task types (that is, `DetectModerationLables` for Amazon Rekognition and `AnalyzeDocument` for Amazon Textract) and permission to use all Amazon A2I API operations, attach the IAM managed policy, `AmazonAugmentedAIIntegratedAPIAccess`. You may want to use this policy when you want to grant broad permissions to a user using Amazon A2I with more than one task type. To learn more about these API operations, see [Use APIs in Amazon Augmented AI](https://docs.amazonaws.cn/sagemaker/latest/dg/a2i-api-references.html).
**Note**
You can also attach the `AmazonAugmentedAIIntegratedAPIAccess` policy to an IAM role that is used to create and start a human loop.
To provide access, add permissions to your users, groups, or roles:
+ Users managed in IAM through an identity provider:
Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*.
+ IAM users:
+ Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*.
+ (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.amazonaws.cn//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*.
For more information, see [Adding and Removing IAM Identity Permissions](https://docs.amazonaws.cn/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) in the *Amazon Identity and Access Management User Guide*.
## Enable Worker Task Template Previews
To customize the interface and instructions that your workers see when working on your tasks, you create a worker task template. You can create the template using the [https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateHumanTaskUi.html](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateHumanTaskUi.html) operation or the SageMaker AI console.
To preview your template, you need an IAM role with the following permissions to read Amazon S3 objects that get rendered on your user interface.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws-cn:s3:::my_input_bucket/*"
]
}
]
}
```
------
For Amazon Rekognition and Amazon Textract task types, you can preview your template using the Amazon Augmented AI section of the SageMaker AI console. For custom task types, you preview your template by invoking the [https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_RenderUiTemplate.html](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_RenderUiTemplate.html) operation. To preview your template, follow the instructions for your task type:
+ Amazon Rekognition and Amazon Textract task types – In the SageMaker AI console, use the role's Amazon Resource Name (ARN) in the procedure documented in [Create a Worker Task Template](a2i-worker-template-console.md#a2i-create-worker-template-console).
+ Custom task types – In the `RenderUiTemplate` operation, use the role's ARN in the `RoleArn` parameter.
## Using Amazon A2I with Amazon KMS Encrypted Buckets
If you specify an Amazon Key Management Service (Amazon KMS) customer managed key to encrypt output data in `OutputConfig` of [https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateFlowDefinition.html](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateFlowDefinition.html), you must add an IAM policy similar to the following to that key. This policy gives the IAM execution role that you use to create your human loops permission to use this key to perform all of the actions listed in `"Action"`. To learn more about these actions, see [Amazon KMS permissions](https://docs.amazonaws.cn/kms/latest/developerguide/kms-api-permissions-reference.html) in the Amazon Key Management Service Developer Guide.
To use this policy, replace the IAM service-role ARN in `"Principal"` with the ARN of the execution role you use to create the human review workflow (flow definition). When you create a labeling job using `CreateFlowDefinition`, this is the ARN you specify for [https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateLabelingJob.html#sagemaker-CreateLabelingJob-request-RoleArn](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateLabelingJob.html#sagemaker-CreateLabelingJob-request-RoleArn). Note that you cannot provide a `KmsKeyId` when you create a flow definition in the console.
```
{
"Sid": "AllowUseOfKmsKey",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/service-role/example-role"
},
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": "*"
}
```
## Additional Permissions and Security Resources
+ [Control access to SageMaker AI resources by using tags](security_iam_id-based-policy-examples.md#access-tag-policy).
+ [Identity-based policies for Amazon SageMaker AI](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies)
+ [Control creation of SageMaker AI resources with condition keys](security_iam_id-based-policy-examples.md#sagemaker-condition-examples)
+ [Amazon SageMaker AI API Permissions: Actions, Permissions, and Resources Reference](api-permissions-reference.md)
+ [Configure security in Amazon SageMaker AI](security.md)
# Use Amazon CloudWatch Events in Amazon Augmented AI
CloudWatch Events
Amazon Augmented AI uses Amazon CloudWatch Events to alert you when a human review loop status changes to `Completed`, `Failed`, or `Stopped`. This event delivery is guaranteed at least once, which means all events created when human loops finish are successfully delivered to CloudWatch Events (Amazon EventBridge). When a review loop changes to one of these states, Augmented AI sends an event to CloudWatch Events similar to the following.
```
{
"version":"0",
"id":"12345678-1111-2222-3333-12345EXAMPLE",
"detail-type":"SageMaker A2I HumanLoop Status Change",
"source":"aws.sagemaker",
"account":"1111111111111",
"time":"2019-11-14T17:49:25Z",
"region":"us-east-1",
"resources":["arn:aws:sagemaker:us-east-1:111111111111:human-loop/humanloop-nov-14-1"],
"detail":{
"creationTime":"2019-11-14T17:37:36.740Z",
"failureCode":null,
"failureReason":null,
"flowDefinitionArn":"arn:aws:sagemaker:us-east-1:111111111111:flow-definition/flowdef-nov-12",
"humanLoopArn":"arn:aws:sagemaker:us-east-1:111111111111:human-loop/humanloop-nov-14-1",
"humanLoopName":"humanloop-nov-14-1",
"humanLoopOutput":{
"outputS3Uri":"s3://customer-output-bucket-specified-in-flow-definition/flowdef-nov-12/2019/11/14/17/37/36/humanloop-nov-14-1/output.json"
},
"humanLoopStatus":"Completed"
}
}
```
The details in the JSON output include the following:
`creationTime`
The timestamp when Augmented AI created the human loop.
`failureCode`
A failure code denoting a specific type of failure.
`failureReason`
The reason why a human loop has failed. The failure reason is only returned when the human review loop status is `failed`.
`flowDefinitionArn`
The Amazon Resource Name (ARN) of the flow definition, or *human review workflow*.
`humanLoopArn`
The Amazon Resource Name (ARN) of the human loop.
`humanLoopName`
The name of the human loop.
`humanLoopOutput`
An object containing information about the output of the human loop.
`outputS3Uri`
The location of the Amazon S3 object where Augmented AI stores your human loop output.
`humanLoopStatus`
The status of the human loop.
## Send Events from Your Human Loop to CloudWatch Events
To configure a CloudWatch Events rule to get status updates, or *events*, for your Amazon A2I human loops, use the Amazon Command Line Interface (Amazon CLI) [https://docs.amazonaws.cn/cli/latest/reference/events/put-rule.html](https://docs.amazonaws.cn/cli/latest/reference/events/put-rule.html) command. When using the `put-rule` command, specify the following to receive human loop statuses:
+ `\"source\":[\"aws.sagemaker\"]`
+ `\"detail-type\":[\"SageMaker A2I HumanLoop Status Change\"]`
To configure a CloudWatch Events rule to watch for all status changes, use the following command and replace the placeholder text. For example, replace `"A2IHumanLoopStatusChanges"` with a unique CloudWatch Events rule name and *`"arn:aws:iam::111122223333:role/MyRoleForThisRule"`* with the Amazon Resource Number (ARN) of an IAM role with an events.amazonaws.com trust policy attached. Replace *region* with the Amazon Region in which you want to create the rule.
```
aws events put-rule --name "A2IHumanLoopStatusChanges"
--event-pattern "{\"source\":[\"aws.sagemaker\"],\"detail-type\":[\"SageMaker A2I HumanLoop Status Change\"]}"
--role-arn "arn:aws:iam::111122223333:role/MyRoleForThisRule"
--region "region"
```
To learn more about the `put-rule` request, see [Event Patterns in CloudWatch Events](https://docs.amazonaws.cn/AmazonCloudWatch/latest/events/CloudWatchEventsandEventPatterns.html) in the *Amazon CloudWatch Events User Guide*.
## Set Up a Target to Process Events
To process events, you need to set up a target. For example, if you want to receive an email when a human loop status changes, use a procedure in [Setting Up Amazon SNS Notifications](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/US_SetupSNS.html) in the *Amazon CloudWatch User Guide *to set up an Amazon SNS topic and subscribe your email to it. Once you have created a topic, you can use it to create a target.
**To add a target to your CloudWatch Events rule**
1. Open the CloudWatch console: [https://console.amazonaws.cn/cloudwatch/home](https://console.amazonaws.cn/cloudwatch/home)
1. In the navigation pane, choose **Rules**.
1. Choose the rule to which you want to add a target.
1. Choose **Actions**, and then choose **Edit**.
1. Under **Targets**, choose **Add Target** and choose the Amazon service you want to act when a human loop status change event is detected.
1. Configure your target. For instructions, see the topic for configuring a target in the [Amazon documentation for that service](https://docs.amazonaws.cn/index.html).
1. Choose **Configure details**.
1. For **Name**, enter a name and, optionally, provide details about the purpose of the rule in **Description**.
1. Make sure that the check box next to **State** is selected so that your rule is listed as **Enabled**.
1. Choose **Update rule**.
## Use Human Review Output
After you receive human review results, you can analyze the results and compare them to machine learning predictions. The JSON that is stored in the Amazon S3 bucket contains both the machine learning predictions and the human review results.
## More Information
[Events that Amazon SageMaker AI sends to Amazon EventBridge](automating-sagemaker-with-eventbridge.md)
# Use APIs in Amazon Augmented AI
API References
You can create a human review workflow or a worker task template programmatically. The APIs you use depend on whether you are creating a Amazon Rekognition, Amazon Textract, or custom task type. This topic provides links to API reference documentation for each task type and programming task.
The following APIs can be used with Augmented AI:
**Amazon Augmented AI**
Use the Augmented AI API to start, stop, and delete human review loops. You can also list all human review loops and return information about human review loops in your account.
Learn more about human review loop APIs in the [Amazon Augmented AI Runtime API Reference](https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/Welcome.html).
**Amazon Rekognition**
Use the **HumanLoopConfig** parameter of the `[ DetectModerationLabels](https://docs.amazonaws.cn/rekognition/latest/dg/API_DetectModerationLabels.html)` API to initiate a human review workflow using Amazon Rekognition.
**Amazon SageMaker AI**
Use the Amazon SageMaker API to create a `FlowDefinition`, also known as a *human review workflow*. You can also create a `HumanTaskUi` or *worker task template*.
For more information, see the [https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateFlowDefinition.html](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateFlowDefinition.html) or the [https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateHumanTaskUi.html](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateHumanTaskUi.html) API documentation.
**Amazon Textract**
Use the **HumanLoopConfig** parameter of the [AnalyzeDocument](https://docs.amazonaws.cn/textract/latest/dg/API_AnalyzeDocument.html) API to initiate a human review workflow using Amazon Textract.
## Programmatic Tutorials
The following tutorials provide example code and step-by-step instructions for creating human review workflows and worker task templates programmatically.
+ [Tutorial: Get Started Using the Amazon A2I API](a2i-get-started-api.md)
+ [Create a Human Review Workflow (API)](a2i-create-flow-definition.md#a2i-create-human-review-api)
+ [Create and Start a Human Loop](a2i-start-human-loop.md)
+ [Using Amazon Augmented AI with Amazon Rekognition](https://docs.amazonaws.cn/rekognition/latest/dg/a2i-rekognition.html) in the *Amazon Rekognition Developer Guide*
+ [Using Amazon Augmented AI with Amazon Textract AnalyzeDocument](https://docs.amazonaws.cn/textract/latest/dg/a2i-textract.html) in the *Amazon Textract Developer Guide*