applications

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

Overview

Name	applications
Type	Resource
Id	aws.qbusiness.applications

Fields

The following fields are returned by SELECT queries:

get_application

Name	Datatype	Description
application_arn	string	The Amazon Resource Name (ARN) of the Amazon Q Business application. (pattern: <code>arn:[a-z0-9-.]{1,63}:[a-z0-9-.]{0,63}:[a-z0-9-.]{0,63}:[a-z0-9-.]{0,63}:[^/].{0,1023}</code>)
application_id	string	The identifier of the Amazon Q Business application. (pattern: <code>[a-zA-Z0-9][a-zA-Z0-9-]{35}</code>)
attachments_configuration	object	Settings for whether end users can upload files directly during chat.
auto_subscription_configuration	object	Settings for auto-subscription behavior for this application. This is only applicable to SAML and OIDC applications.
client_ids_for_oidc	array	The OIDC client ID for a Amazon Q Business application.
created_at	string (date-time)	The Unix timestamp when the Amazon Q Business application was last updated.
description	string	A description for the Amazon Q Business application. (pattern: <code>[\s\S]*</code>)
display_name	string	The name of the Amazon Q Business application. (pattern: <code>[a-zA-Z0-9][a-zA-Z0-9_-]*</code>)
encryption_configuration	object	Provides the identifier of the KMS key used to encrypt data indexed by Amazon Q Business. Amazon Q Business doesn't support asymmetric keys.
error	object	If the Status field is set to ERROR, the ErrorMessage field contains a description of the error that caused the synchronization to fail.
iam_identity_provider_arn	string	The Amazon Resource Name (ARN) of an identity provider being used by an Amazon Q Business application. (pattern: <code>arn:[a-z0-9-.]{1,63}:iam::\d{12}:(oidc-provider|saml-provider)/[a-zA-Z0-9_./@-]+</code>)
identity_center_application_arn	string	The Amazon Resource Name (ARN) of the AWS IAM Identity Center instance attached to your Amazon Q Business application. (pattern: <code>arn:[a-z0-9-.]{1,63}:sso::\d{12}:application/(sso)?ins-[a-zA-Z0-9-.]{16}/apl-[a-zA-Z0-9]{16}</code>)
identity_type	string	The authentication type being used by a Amazon Q Business application. (AWS_IAM_IDP_SAML, AWS_IAM_IDP_OIDC, AWS_IAM_IDC, AWS_QUICKSIGHT_IDP, ANONYMOUS)
personalization_configuration	object	Configuration information about chat response personalization. For more information, see Personalizing chat responses.
q_apps_configuration	object	Configuration information about Amazon Q Apps.
quick_sight_configuration	object	The Amazon Quick Suite configuration for an Amazon Q Business application that uses Quick Suite as the identity provider. For more information, see Creating an Amazon Quick Suite integrated application.
role_arn	string	The Amazon Resource Name (ARN) of the IAM with permissions to access your CloudWatch logs and metrics. (pattern: <code>arn:[a-z0-9-.]{1,63}:[a-z0-9-.]{0,63}:[a-z0-9-.]{0,63}:[a-z0-9-.]{0,63}:[^/].{0,1023}</code>)
status	string	The status of the Amazon Q Business application. (CREATING, ACTIVE, DELETING, FAILED, UPDATING)
updated_at	string (date-time)	The Unix timestamp when the Amazon Q Business application was last updated.

list_applications

Name	Datatype	Description
application_id	string	The identifier for the Amazon Q Business application. (pattern: <code>[a-zA-Z0-9][a-zA-Z0-9-]{35}</code>)
created_at	string (date-time)	The Unix timestamp when the Amazon Q Business application was created.
display_name	string	The name of the Amazon Q Business application. (pattern: <code>[a-zA-Z0-9][a-zA-Z0-9_-]*</code>)
identity_type	string	The authentication type being used by a Amazon Q Business application. (AWS_IAM_IDP_SAML, AWS_IAM_IDP_OIDC, AWS_IAM_IDC, AWS_QUICKSIGHT_IDP, ANONYMOUS)
quick_sight_configuration	object	The Amazon Quick Suite configuration for an Amazon Q Business application that uses Quick Suite as the identity provider. For more information, see Creating an Amazon Quick Suite integrated application.
status	string	The status of the Amazon Q Business application. The application is ready to use when the status is ACTIVE. (CREATING, ACTIVE, DELETING, FAILED, UPDATING)
updated_at	string (date-time)	The Unix timestamp when the Amazon Q Business application was last updated.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_application	select	application_id, region		Gets information about an existing Amazon Q Business application.
list_applications	select	region	nextToken, maxResults	Lists Amazon Q Business applications. Amazon Q Business applications may securely transmit data for processing across Amazon Web Services Regions within your geography. For more information, see Cross region inference in Amazon Q Business.
create_application	insert	region, displayName		Creates an Amazon Q Business application. There are new tiers for Amazon Q Business. Not all features in Amazon Q Business Pro are also available in Amazon Q Business Lite. For information on what's included in Amazon Q Business Lite and what's included in Amazon Q Business Pro, see Amazon Q Business tiers. You must use the Amazon Q Business console to assign subscription tiers to users. An Amazon Q Apps service linked role will be created if it's absent in the Amazon Web Services account when QAppsConfiguration is enabled in the request. For more information, see Using service-linked roles for Q Apps. When you create an application, Amazon Q Business may securely transmit data for processing from your selected Amazon Web Services region, but within your geography. For more information, see Cross region inference in Amazon Q Business.
associate_permission	update	application_id, region, statementId, actions, principal		Adds or updates a permission policy for a Amazon Q Business application, allowing cross-account access for an ISV. This operation creates a new policy statement for the specified Amazon Q Business application. The policy statement defines the IAM actions that the ISV is allowed to perform on the Amazon Q Business application's resources.
disassociate_permission	update	application_id, statement_id, region		Removes a permission policy from a Amazon Q Business application, revoking the cross-account access that was previously granted to an ISV. This operation deletes the specified policy statement from the application's permission policy.
update_application	update	application_id, region		Updates an existing Amazon Q Business application. Amazon Q Business applications may securely transmit data for processing across Amazon Web Services Regions within your geography. For more information, see Cross region inference in Amazon Q Business. An Amazon Q Apps service-linked role will be created if it's absent in the Amazon Web Services account when QAppsConfiguration is enabled in the request. For more information, see Using service-linked roles for Q Apps.
delete_application	delete	application_id, region		Deletes an Amazon Q Business application.
batch_delete_document	exec	application_id, index_id, region, documents		Asynchronously deletes one or more documents added using the BatchPutDocument API from an Amazon Q Business index. You can see the progress of the deletion, and any error messages related to the process, by using CloudWatch.
batch_put_document	exec	application_id, index_id, region, documents		Adds one or more documents to an Amazon Q Business index. You use this API to: ingest your structured and unstructured documents and documents stored in an Amazon S3 bucket into an Amazon Q Business index. add custom attributes to documents in an Amazon Q Business index. attach an access control list to the documents added to an Amazon Q Business index. You can see the progress of the deletion, and any error messages related to the process, by using CloudWatch.
chat	exec	application_id, region	userId, userGroups, conversationId, parentMessageId, clientToken	Starts or continues a streaming Amazon Q Business conversation.
chat_sync	exec	application_id, region	userId, userGroups	Starts or continues a non-streaming Amazon Q Business conversation.
check_document_access	exec	application_id, index_id, user_id, document_id, region	dataSourceId	Verifies if a user has access permissions for a specified document and returns the actual ACL attached to the document. Resolves user access on the document via user aliases and groups when verifying user access.

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
application_id	string	The unique identifier of the application. This is required to identify the specific Amazon Q Business application context for the document access check.
document_id	string	The unique identifier of the document. Specifies which document's access permissions are being checked.
index_id	string	The unique identifier of the index. Used to locate the correct index within the application where the document is stored.
region	string	AWS region (default: us-east-1)
statement_id	string	The statement ID of the permission to remove.
user_id	string	The unique identifier of the user. Used to check the access permissions for this specific user against the document's ACL.
clientToken	string	A token that you provide to identify the chat input.
conversationId	string	The identifier of the Amazon Q Business conversation.
dataSourceId	string	The unique identifier of the data source. Identifies the specific data source from which the document originates. Should not be used when a document is uploaded directly with BatchPutDocument, as no dataSourceId is available or necessary.
maxResults	integer	The maximum number of Amazon Q Business applications to return.
nextToken	string	If the maxResults response was incomplete because there is more data to retrieve, Amazon Q Business returns a pagination token in the response. You can use this pagination token to retrieve the next set of Amazon Q Business applications.
parentMessageId	string	The identifier used to associate a user message with a AI generated response.
userGroups	array	The group names that a user associated with the chat input belongs to.
userId	string	The identifier of the user attached to the chat input.

SELECT examples

get_application

Gets information about an existing Amazon Q Business application.

SELECT
application_arn,
application_id,
attachments_configuration,
auto_subscription_configuration,
client_ids_for_oidc,
created_at,
description,
display_name,
encryption_configuration,
error,
iam_identity_provider_arn,
identity_center_application_arn,
identity_type,
personalization_configuration,
q_apps_configuration,
quick_sight_configuration,
role_arn,
status,
updated_at
FROM aws.qbusiness.applications
WHERE application_id = '{{ application_id }}' -- required
AND region = '{{ region }}' -- required
;

list_applications

Lists Amazon Q Business applications. Amazon Q Business applications may securely transmit data for processing across Amazon Web Services Regions within your geography. For more information, see Cross region inference in Amazon Q Business.

SELECT
application_id,
created_at,
display_name,
identity_type,
quick_sight_configuration,
status,
updated_at
FROM aws.qbusiness.applications
WHERE region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
;

INSERT examples

create_application

Creates an Amazon Q Business application. There are new tiers for Amazon Q Business. Not all features in Amazon Q Business Pro are also available in Amazon Q Business Lite. For information on what's included in Amazon Q Business Lite and what's included in Amazon Q Business Pro, see Amazon Q Business tiers. You must use the Amazon Q Business console to assign subscription tiers to users. An Amazon Q Apps service linked role will be created if it's absent in the Amazon Web Services account when QAppsConfiguration is enabled in the request. For more information, see Using service-linked roles for Q Apps. When you create an application, Amazon Q Business may securely transmit data for processing from your selected Amazon Web Services region, but within your geography. For more information, see Cross region inference in Amazon Q Business.

INSERT INTO aws.qbusiness.applications (
displayName,
roleArn,
identityType,
iamIdentityProviderArn,
identityCenterInstanceArn,
clientIdsForOIDC,
description,
encryptionConfiguration,
tags,
clientToken,
attachmentsConfiguration,
qAppsConfiguration,
personalizationConfiguration,
quickSightConfiguration,
region
)
SELECT 
'{{ displayName }}' /* required */,
'{{ roleArn }}',
'{{ identityType }}',
'{{ iamIdentityProviderArn }}',
'{{ identityCenterInstanceArn }}',
'{{ clientIdsForOIDC }}',
'{{ description }}',
'{{ encryptionConfiguration }}',
'{{ tags }}',
'{{ clientToken }}',
'{{ attachmentsConfiguration }}',
'{{ qAppsConfiguration }}',
'{{ personalizationConfiguration }}',
'{{ quickSightConfiguration }}',
'{{ region }}'
RETURNING
application_arn,
application_id
;

Manifest

# Description fields are for documentation purposes
- name: applications
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the applications resource.
  - name: displayName
    value: "{{ displayName }}"
  - name: roleArn
    value: "{{ roleArn }}"
  - name: identityType
    value: "{{ identityType }}"
    valid_values: ['AWS_IAM_IDP_SAML', 'AWS_IAM_IDP_OIDC', 'AWS_IAM_IDC', 'AWS_QUICKSIGHT_IDP', 'ANONYMOUS']
  - name: iamIdentityProviderArn
    value: "{{ iamIdentityProviderArn }}"
  - name: identityCenterInstanceArn
    value: "{{ identityCenterInstanceArn }}"
  - name: clientIdsForOIDC
    value:
      - "{{ clientIdsForOIDC }}"
  - name: description
    value: "{{ description }}"
  - name: encryptionConfiguration
    description: |
      Provides the identifier of the KMS key used to encrypt data indexed by Amazon Q Business. Amazon Q Business doesn't support asymmetric keys.
    value:
      kmsKeyId: "{{ kmsKeyId }}"
  - name: tags
    value:
      - key: "{{ key }}"
        value: "{{ value }}"
  - name: clientToken
    value: "{{ clientToken }}"
  - name: attachmentsConfiguration
    description: |
      Configuration information for the file upload during chat feature.
    value:
      attachmentsControlMode: "{{ attachmentsControlMode }}"
  - name: qAppsConfiguration
    description: |
      Configuration information about Amazon Q Apps.
    value:
      qAppsControlMode: "{{ qAppsControlMode }}"
  - name: personalizationConfiguration
    description: |
      Configuration information about chat response personalization. For more information, see Personalizing chat responses.
    value:
      personalizationControlMode: "{{ personalizationControlMode }}"
  - name: quickSightConfiguration
    description: |
      The Amazon Quick Suite configuration for an Amazon Q Business application that uses Quick Suite as the identity provider. For more information, see Creating an Amazon Quick Suite integrated application.
    value:
      clientNamespace: "{{ clientNamespace }}"

UPDATE examples

associate_permission

Adds or updates a permission policy for a Amazon Q Business application, allowing cross-account access for an ISV. This operation creates a new policy statement for the specified Amazon Q Business application. The policy statement defines the IAM actions that the ISV is allowed to perform on the Amazon Q Business application's resources.

UPDATE aws.qbusiness.applications
SET 
statementId = '{{ statementId }}',
actions = '{{ actions }}',
conditions = '{{ conditions }}',
principal = '{{ principal }}'
WHERE 
application_id = '{{ application_id }}' --required
AND region = '{{ region }}' --required
AND statementId = '{{ statementId }}' --required
AND actions = '{{ actions }}' --required
AND principal = '{{ principal }}' --required
RETURNING
statement;

disassociate_permission

Removes a permission policy from a Amazon Q Business application, revoking the cross-account access that was previously granted to an ISV. This operation deletes the specified policy statement from the application's permission policy.

UPDATE aws.qbusiness.applications
SET 
-- No updatable properties
WHERE 
application_id = '{{ application_id }}' --required
AND statement_id = '{{ statement_id }}' --required
AND region = '{{ region }}' --required;

update_application

Updates an existing Amazon Q Business application. Amazon Q Business applications may securely transmit data for processing across Amazon Web Services Regions within your geography. For more information, see Cross region inference in Amazon Q Business. An Amazon Q Apps service-linked role will be created if it's absent in the Amazon Web Services account when QAppsConfiguration is enabled in the request. For more information, see Using service-linked roles for Q Apps.

UPDATE aws.qbusiness.applications
SET 
identityCenterInstanceArn = '{{ identityCenterInstanceArn }}',
displayName = '{{ displayName }}',
description = '{{ description }}',
roleArn = '{{ roleArn }}',
attachmentsConfiguration = '{{ attachmentsConfiguration }}',
qAppsConfiguration = '{{ qAppsConfiguration }}',
personalizationConfiguration = '{{ personalizationConfiguration }}',
autoSubscriptionConfiguration = '{{ autoSubscriptionConfiguration }}'
WHERE 
application_id = '{{ application_id }}' --required
AND region = '{{ region }}' --required;

DELETE examples

delete_application

Deletes an Amazon Q Business application.

DELETE FROM aws.qbusiness.applications
WHERE application_id = '{{ application_id }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

batch_delete_document

Asynchronously deletes one or more documents added using the BatchPutDocument API from an Amazon Q Business index. You can see the progress of the deletion, and any error messages related to the process, by using CloudWatch.

EXEC aws.qbusiness.applications.batch_delete_document 
@application_id='{{ application_id }}' --required, 
@index_id='{{ index_id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"documents": "{{ documents }}", 
"dataSourceSyncId": "{{ dataSourceSyncId }}"
}'
;

batch_put_document

Adds one or more documents to an Amazon Q Business index. You use this API to: ingest your structured and unstructured documents and documents stored in an Amazon S3 bucket into an Amazon Q Business index. add custom attributes to documents in an Amazon Q Business index. attach an access control list to the documents added to an Amazon Q Business index. You can see the progress of the deletion, and any error messages related to the process, by using CloudWatch.

EXEC aws.qbusiness.applications.batch_put_document 
@application_id='{{ application_id }}' --required, 
@index_id='{{ index_id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"documents": "{{ documents }}", 
"roleArn": "{{ roleArn }}", 
"dataSourceSyncId": "{{ dataSourceSyncId }}"
}'
;

chat

Starts or continues a streaming Amazon Q Business conversation.

EXEC aws.qbusiness.applications.chat 
@application_id='{{ application_id }}' --required, 
@region='{{ region }}' --required, 
@userId='{{ userId }}', 
@userGroups='{{ userGroups }}', 
@conversationId='{{ conversationId }}', 
@parentMessageId='{{ parentMessageId }}', 
@clientToken='{{ clientToken }}' 
@@json=
'{
"inputStream": "{{ inputStream }}"
}'
;

chat_sync

Starts or continues a non-streaming Amazon Q Business conversation.

EXEC aws.qbusiness.applications.chat_sync 
@application_id='{{ application_id }}' --required, 
@region='{{ region }}' --required, 
@userId='{{ userId }}', 
@userGroups='{{ userGroups }}' 
@@json=
'{
"userMessage": "{{ userMessage }}", 
"attachments": "{{ attachments }}", 
"actionExecution": "{{ actionExecution }}", 
"authChallengeResponse": "{{ authChallengeResponse }}", 
"conversationId": "{{ conversationId }}", 
"parentMessageId": "{{ parentMessageId }}", 
"attributeFilter": "{{ attributeFilter }}", 
"chatMode": "{{ chatMode }}", 
"chatModeConfiguration": "{{ chatModeConfiguration }}", 
"clientToken": "{{ clientToken }}"
}'
;

check_document_access

Verifies if a user has access permissions for a specified document and returns the actual ACL attached to the document. Resolves user access on the document via user aliases and groups when verifying user access.

EXEC aws.qbusiness.applications.check_document_access 
@application_id='{{ application_id }}' --required, 
@index_id='{{ index_id }}' --required, 
@user_id='{{ user_id }}' --required, 
@document_id='{{ document_id }}' --required, 
@region='{{ region }}' --required, 
@dataSourceId='{{ dataSourceId }}'
;