evaluation_forms

Creates, updates, deletes, gets or lists an evaluation_forms resource.

Overview

Name	evaluation_forms
Type	Resource
Id	aws.connect.evaluation_forms

Fields

The following fields are returned by SELECT queries:

describe_evaluation_form

Name	Datatype	Description
auto_evaluation_configuration	object	The automatic evaluation configuration of an evaluation form.
created_by	string	The Amazon Resource Name (ARN) of the user who created the evaluation form.
created_time	string (date-time)	The timestamp for when the evaluation form was created.
description	string	The description of the evaluation form.
evaluation_form_arn	string	The Amazon Resource Name (ARN) for the evaluation form resource.
evaluation_form_id	string	The unique identifier for the evaluation form.
evaluation_form_version	integer	A version of the evaluation form.
items	array	Items that are part of the evaluation form. The total number of sections and questions must not exceed 100 each. Questions must be contained in a section.
language_configuration	object	Language configuration for an evaluation form.
last_modified_by	string	The Amazon Resource Name (ARN) of the user who last updated the evaluation form.
last_modified_time	string (date-time)	The timestamp for when the evaluation form was last updated.
last_validation_time	string (date-time)	The timestamp when the most recent validation was started for this evaluation form.
latest_validation_status	string	The status of the most recent validation run for this evaluation form. Valid values: IN_PROGRESS, COMPLETED, FAILED. (IN_PROGRESS, COMPLETED, FAILED)
locked	boolean	The flag indicating whether the evaluation form is locked for changes.
review_configuration	object	Configuration settings for evaluation reviews.
scoring_strategy	object	Information about scoring strategy for an evaluation form.
status	string	The status of the evaluation form. (DRAFT, ACTIVE)
tags	object	The tags used to organize, track, or control access for this resource. For example, { "Tags": {"key1":"value1", "key2":"value2"} }.
target_configuration	object	Configuration that specifies the target for an evaluation form.
title	string	A title of the evaluation form.

list_evaluation_forms

Name	Datatype	Description
active_version	integer	The version of the active evaluation form version.
created_by	string	The Amazon Resource Name (ARN) of the user who created the evaluation form.
created_time	string (date-time)	The timestamp for when the evaluation form was created.
evaluation_form_arn	string	The Amazon Resource Name (ARN) for the evaluation form resource.
evaluation_form_id	string	The unique identifier for the evaluation form.
last_activated_by	string	The Amazon Resource Name (ARN) of the user who last activated the evaluation form.
last_activated_time	string (date-time)	The timestamp for when the evaluation form was last activated.
last_modified_by	string	The Amazon Resource Name (ARN) of the user who last updated the evaluation form.
last_modified_time	string (date-time)	The timestamp for when the evaluation form was last updated.
latest_version	integer	The version number of the latest evaluation form version.
title	string	A title of the evaluation form.

search_evaluation_forms

Name	Datatype	Description
approximate_total_count	integer (int64)	The total number of evaluation forms that matched your search query.
evaluation_form_search_summary_list	array	Information about the returned evaluation forms.
next_token	string	If there are additional results, this is the token for the next set of results.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_evaluation_form	select	instance_id, evaluation_form_id, region	version	Describes an evaluation form in the specified Connect Customer instance. If the version property is not provided, the latest version of the evaluation form is described.
list_evaluation_forms	select	instance_id, region	maxResults, nextToken	Lists evaluation forms in the specified Connect Customer instance.
search_evaluation_forms	select	region		Searches evaluation forms in an Connect Customer instance, with optional filtering. Use cases Following are common uses cases for this API: List all evaluation forms in an instance. Find all evaluation forms that meet specific criteria, such as Title, Description, Status, and more. Find all evaluation forms that are tagged with a specific set of tags. Important things to know A Search operation, unlike a List operation, takes time to index changes to resource (create, update or delete). If you don't see updated information for recently changed contact evaluations, try calling the API again in a few seconds. Endpoints: See Connect Customer endpoints and quotas.
create_evaluation_form	insert	instance_id, region, Items		Creates an evaluation form in the specified Connect Customer instance. The form can be used to define questions related to agent performance, and create sections to organize such questions. Question and section identifiers cannot be duplicated within the same evaluation form.
update_evaluation_form	update	instance_id, evaluation_form_id, region, EvaluationFormVersion, Items		Updates details about a specific evaluation form version in the specified Connect Customer instance. Question and section identifiers cannot be duplicated within the same evaluation form. This operation does not support partial updates. Instead it does a full update of evaluation form content.
delete_evaluation_form	delete	instance_id, evaluation_form_id, region	version	Deletes an evaluation form in the specified Connect Customer instance. If the version property is provided, only the specified version of the evaluation form is deleted. If no version is provided, then the full form (all versions) is deleted.
activate_evaluation_form	exec	instance_id, evaluation_form_id, region, EvaluationFormVersion		Activates an evaluation form in the specified Connect Customer instance. After the evaluation form is activated, it is available to start new evaluations based on the form.
deactivate_evaluation_form	exec	instance_id, evaluation_form_id, region, EvaluationFormVersion		Deactivates an evaluation form in the specified Connect Customer instance. After a form is deactivated, it is no longer available for users to start new evaluations based on the form.
start_evaluation_form_validation	exec	instance_id, evaluation_form_id, region, EvaluationFormVersion		Starts an asynchronous validation process for an evaluation form version in the specified Connect Customer instance. The validation first performs structural checks on the form content (such as verifying required fields, valid scoring configuration, and correct conditional logic), then asynchronously analyzes questions configured for generative AI evaluation against a set of best practices. Use GetEvaluationFormValidation to retrieve the status and results once the validation completes.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
evaluation_form_id	string	The unique identifier for the evaluation form.
instance_id	string	The identifier of the Connect Customer instance. You can find the instance ID in the Amazon Resource Name (ARN) of the instance.
region	string	AWS region (default: us-east-1)
maxResults	integer	The maximum number of results to return per page.
nextToken	string	The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results.
version	integer	The unique identifier for the evaluation form.

SELECT examples

describe_evaluation_form

Describes an evaluation form in the specified Connect Customer instance. If the version property is not provided, the latest version of the evaluation form is described.

SELECT
auto_evaluation_configuration,
created_by,
created_time,
description,
evaluation_form_arn,
evaluation_form_id,
evaluation_form_version,
items,
language_configuration,
last_modified_by,
last_modified_time,
last_validation_time,
latest_validation_status,
locked,
review_configuration,
scoring_strategy,
status,
tags,
target_configuration,
title
FROM aws.connect.evaluation_forms
WHERE instance_id = '{{ instance_id }}' -- required
AND evaluation_form_id = '{{ evaluation_form_id }}' -- required
AND region = '{{ region }}' -- required
AND version = '{{ version }}'
;

list_evaluation_forms

Lists evaluation forms in the specified Connect Customer instance.

SELECT
active_version,
created_by,
created_time,
evaluation_form_arn,
evaluation_form_id,
last_activated_by,
last_activated_time,
last_modified_by,
last_modified_time,
latest_version,
title
FROM aws.connect.evaluation_forms
WHERE instance_id = '{{ instance_id }}' -- required
AND region = '{{ region }}' -- required
AND maxResults = '{{ maxResults }}'
AND nextToken = '{{ nextToken }}'
;

search_evaluation_forms

Searches evaluation forms in an Connect Customer instance, with optional filtering. Use cases Following are common uses cases for this API: List all evaluation forms in an instance. Find all evaluation forms that meet specific criteria, such as Title, Description, Status, and more. Find all evaluation forms that are tagged with a specific set of tags. Important things to know A Search operation, unlike a List operation, takes time to index changes to resource (create, update or delete). If you don't see updated information for recently changed contact evaluations, try calling the API again in a few seconds. Endpoints: See Connect Customer endpoints and quotas.

SELECT
approximate_total_count,
evaluation_form_search_summary_list,
next_token
FROM aws.connect.evaluation_forms
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_evaluation_form

Creates an evaluation form in the specified Connect Customer instance. The form can be used to define questions related to agent performance, and create sections to organize such questions. Question and section identifiers cannot be duplicated within the same evaluation form.

INSERT INTO aws.connect.evaluation_forms (
Title,
Description,
Items,
ScoringStrategy,
AutoEvaluationConfiguration,
ClientToken,
AsDraft,
Tags,
ReviewConfiguration,
TargetConfiguration,
LanguageConfiguration,
instance_id,
region
)
SELECT 
'{{ Title }}',
'{{ Description }}',
'{{ Items }}' /* required */,
'{{ ScoringStrategy }}',
'{{ AutoEvaluationConfiguration }}',
'{{ ClientToken }}',
{{ AsDraft }},
'{{ Tags }}',
'{{ ReviewConfiguration }}',
'{{ TargetConfiguration }}',
'{{ LanguageConfiguration }}',
'{{ instance_id }}',
'{{ region }}'
RETURNING
evaluation_form_arn,
evaluation_form_id
;

Manifest

# Description fields are for documentation purposes
- name: evaluation_forms
props:
  - name: instance_id
    value: "{{ instance_id }}"
    description: Required parameter for the evaluation_forms resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the evaluation_forms resource.
  - name: Title
    value: "{{ Title }}"
  - name: Description
    value: "{{ Description }}"
  - name: Items
    value:
      - Section:
          Title: "{{ Title }}"
          RefId: "{{ RefId }}"
          Instructions: "{{ Instructions }}"
          Items: "{{ Items }}"
          Weight: {{ Weight }}
          IsExcludedFromScoring: {{ IsExcludedFromScoring }}
          ScoreThresholds:
            - PerformanceCategory: "{{ PerformanceCategory }}"
              MinScorePercentage: {{ MinScorePercentage }}
              MaxScorePercentage: {{ MaxScorePercentage }}
        Question:
          Title: "{{ Title }}"
          Instructions: "{{ Instructions }}"
          RefId: "{{ RefId }}"
          NotApplicableEnabled: {{ NotApplicableEnabled }}
          QuestionType: "{{ QuestionType }}"
          QuestionTypeProperties:
            Numeric:
              MinValue: {{ MinValue }}
              MaxValue: {{ MaxValue }}
              Options:
                - MinValue: {{ MinValue }}
                  MaxValue: {{ MaxValue }}
                  Score: {{ Score }}
                  AutomaticFail: {{ AutomaticFail }}
                  AutomaticFailConfiguration:
                    TargetSection: "{{ TargetSection }}"
                  PointsConfiguration:
                    PointValue: {{ PointValue }}
                    IsBonus: {{ IsBonus }}
              Automation:
                PropertyValue: "{{ PropertyValue }}"
                AnswerSource: "{{ AnswerSource }}"
            SingleSelect:
              Options:
                - RefId: "{{ RefId }}"
                  Text: "{{ Text }}"
                  Score: {{ Score }}
                  AutomaticFail: {{ AutomaticFail }}
                  AutomaticFailConfiguration:
                    TargetSection: "{{ TargetSection }}"
                  PointsConfiguration:
                    PointValue: {{ PointValue }}
                    IsBonus: {{ IsBonus }}
              DisplayAs: "{{ DisplayAs }}"
              Automation:
                Options: "{{ Options }}"
                DefaultOptionRefId: "{{ DefaultOptionRefId }}"
                AnswerSource: "{{ AnswerSource }}"
            Text:
              Automation:
                AnswerSource: "{{ AnswerSource }}"
            MultiSelect:
              Options:
                - RefId: "{{ RefId }}"
                  Text: "{{ Text }}"
                  Score: {{ Score }}
                  AutomaticFail: {{ AutomaticFail }}
                  AutomaticFailConfiguration:
                    TargetSection: "{{ TargetSection }}"
                  PointsConfiguration:
                    PointValue: {{ PointValue }}
                    IsBonus: {{ IsBonus }}
              DisplayAs: "{{ DisplayAs }}"
              Automation:
                Options: "{{ Options }}"
                DefaultOptionRefIds: "{{ DefaultOptionRefIds }}"
                AnswerSource: "{{ AnswerSource }}"
          Enablement:
            Condition:
              Operands:
                - Expression:
                    Source: "{{ Source }}"
                    Values: "{{ Values }}"
                    Comparator: "{{ Comparator }}"
                  Condition:
                    Operands: "{{ Operands }}"
                    Operator: "{{ Operator }}"
              Operator: "{{ Operator }}"
            Action: "{{ Action }}"
            DefaultAction: "{{ DefaultAction }}"
          Weight: {{ Weight }}
          ScoringConfiguration:
            PointsConfiguration:
              MaxPointValue: {{ MaxPointValue }}
              MinPointValue: {{ MinPointValue }}
              IsBonus: {{ IsBonus }}
            IsExcludedFromScoring: {{ IsExcludedFromScoring }}
            ScoreThresholds:
              - PerformanceCategory: "{{ PerformanceCategory }}"
                MinScorePercentage: {{ MinScorePercentage }}
                MaxScorePercentage: {{ MaxScorePercentage }}
  - name: ScoringStrategy
    description: |
      Information about scoring strategy for an evaluation form.
    value:
      Mode: "{{ Mode }}"
      Status: "{{ Status }}"
      ScoreThresholds:
        - PerformanceCategory: "{{ PerformanceCategory }}"
          MinScorePercentage: {{ MinScorePercentage }}
          MaxScorePercentage: {{ MaxScorePercentage }}
  - name: AutoEvaluationConfiguration
    description: |
      The automatic evaluation configuration of an evaluation form.
    value:
      Enabled: {{ Enabled }}
  - name: ClientToken
    value: "{{ ClientToken }}"
  - name: AsDraft
    value: {{ AsDraft }}
  - name: Tags
    value: "{{ Tags }}"
  - name: ReviewConfiguration
    description: |
      Configuration settings for evaluation reviews.
    value:
      ReviewNotificationRecipients:
        - Type: "{{ Type }}"
          Value:
            UserId: "{{ UserId }}"
      EligibilityDays: {{ EligibilityDays }}
  - name: TargetConfiguration
    description: |
      Configuration that specifies the target for an evaluation form.
    value:
      ContactInteractionType: "{{ ContactInteractionType }}"
  - name: LanguageConfiguration
    description: |
      Language configuration for an evaluation form.
    value:
      FormLanguage: "{{ FormLanguage }}"

UPDATE examples

update_evaluation_form

Updates details about a specific evaluation form version in the specified Connect Customer instance. Question and section identifiers cannot be duplicated within the same evaluation form. This operation does not support partial updates. Instead it does a full update of evaluation form content.

UPDATE aws.connect.evaluation_forms
SET 
EvaluationFormVersion = {{ EvaluationFormVersion }},
CreateNewVersion = {{ CreateNewVersion }},
Title = '{{ Title }}',
Description = '{{ Description }}',
Items = '{{ Items }}',
ScoringStrategy = '{{ ScoringStrategy }}',
AutoEvaluationConfiguration = '{{ AutoEvaluationConfiguration }}',
ReviewConfiguration = '{{ ReviewConfiguration }}',
AsDraft = {{ AsDraft }},
ClientToken = '{{ ClientToken }}',
TargetConfiguration = '{{ TargetConfiguration }}',
LanguageConfiguration = '{{ LanguageConfiguration }}'
WHERE 
instance_id = '{{ instance_id }}' --required
AND evaluation_form_id = '{{ evaluation_form_id }}' --required
AND region = '{{ region }}' --required
AND EvaluationFormVersion = '{{ EvaluationFormVersion }}' --required
AND Items = '{{ Items }}' --required
RETURNING
evaluation_form_arn,
evaluation_form_id,
evaluation_form_version;

DELETE examples

delete_evaluation_form

Deletes an evaluation form in the specified Connect Customer instance. If the version property is provided, only the specified version of the evaluation form is deleted. If no version is provided, then the full form (all versions) is deleted.

DELETE FROM aws.connect.evaluation_forms
WHERE instance_id = '{{ instance_id }}' --required
AND evaluation_form_id = '{{ evaluation_form_id }}' --required
AND region = '{{ region }}' --required
AND version = '{{ version }}'
;

Lifecycle Methods

activate_evaluation_form

Activates an evaluation form in the specified Connect Customer instance. After the evaluation form is activated, it is available to start new evaluations based on the form.

EXEC aws.connect.evaluation_forms.activate_evaluation_form 
@instance_id='{{ instance_id }}' --required, 
@evaluation_form_id='{{ evaluation_form_id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"EvaluationFormVersion": {{ EvaluationFormVersion }}
}'
;

deactivate_evaluation_form

Deactivates an evaluation form in the specified Connect Customer instance. After a form is deactivated, it is no longer available for users to start new evaluations based on the form.

EXEC aws.connect.evaluation_forms.deactivate_evaluation_form 
@instance_id='{{ instance_id }}' --required, 
@evaluation_form_id='{{ evaluation_form_id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"EvaluationFormVersion": {{ EvaluationFormVersion }}
}'
;

start_evaluation_form_validation

Starts an asynchronous validation process for an evaluation form version in the specified Connect Customer instance. The validation first performs structural checks on the form content (such as verifying required fields, valid scoring configuration, and correct conditional logic), then asynchronously analyzes questions configured for generative AI evaluation against a set of best practices. Use GetEvaluationFormValidation to retrieve the status and results once the validation completes.

EXEC aws.connect.evaluation_forms.start_evaluation_form_validation 
@instance_id='{{ instance_id }}' --required, 
@evaluation_form_id='{{ evaluation_form_id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"EvaluationFormVersion": {{ EvaluationFormVersion }}
}'
;