{
"aemUrl": "Adobe Experience Manager On-Premise host URL",
"username": "username with admin permissions",
"password": "password with admin permissions"
} If using OAuth 2.0 authentication for AEM On-Premise: {
"aemUrl": "Adobe Experience Manager host URL",
"clientId": "client ID",
"clientSecret": "client secret",
"privateKey": "private key"
} If using OAuth 2.0 authentication for AEM as a Cloud Service: {
"clientId": "client ID",
"clientSecret": "client secret",
"privateKey": "private key",
"orgId": "organization ID",
"technicalAccountId": "technical account ID",
"imsHost": "Adobe Identity Management System (IMS) host"
} |
| version | The version of this template that's currently supported. |
# How Amazon Q Business connector crawls AEM (Cloud) ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an AEM (Cloud) data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your AEM (Cloud) instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
The group and user IDs are mapped as follows:
+ `_group_ids` – Group IDs exist in Adobe Experience Manager content where there are set access permissions. They're mapped from the names of the groups in AEM.
+ `_user_id` – User IDs exist in Adobe Experience Manager content where there are set access permissions. They're mapped from the user emails as the IDs in AEM.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Amazon Q Business AEM (Cloud) data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application environment and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Adobe Experience Manager (AEM) connector supports the following entities and the associated reserved and custom attributes.
**Important**
If you map any AEM (Cloud) field to Amazon Q document title and document body fields, Amazon Q will generate responses from data in the document title and body.
**Topics**
+ [
## Pages
](#aem-field-mappings-pages)
+ [
## Assets
](#aem-field-mappings-assets)
## Pages
Amazon Q supports crawling [AEM Pages](https://experienceleague.adobe.com/docs/experience-manager-cloud-service/content/assets/overview.html?lang=en) and offers the following page field mappings.
| Adobe Experience Manager (AEM) field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| aem\$1page\$1source\$1uri | \$1source\$1uri | Default | String |
| aem\$1page\$1createdBy | \$1authors | Default | String list |
| aem\$1page\$1template | aem\$1page\$1template | Custom | String |
| aem\$1entity\$1type | \$1category | Default | String |
| aem\$1page\$1createdAt | \$1created\$1at | Default | Date |
| aem\$1page\$1lastModified | \$1last\$1updated\$1at | Default | Date |
| aem\$1page\$1lastReplicatedBy | aem\$1page\$1publisher | Custom | String |
| aem\$1page\$1lastReplicatedAt | aem\$1page\$1publishedAt | Custom | Date |
## Assets
Amazon Q supports crawling [AEM Assets](https://experienceleague.adobe.com/docs/experience-manager-cloud-service/content/assets/overview.html?lang=en) and offers the following asset field mappings.
| Adobe Experience Manager (AEM) field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| aem\$1page\$1source\$1uri | \$1source\$1uri | Default | String |
| aem\$1page\$1createdBy | \$1authors | Default | String list |
| aem\$1entity\$1type | \$1category | Default | String |
| aem\$1page\$1createdAt | \$1created\$1at | Default | Date |
| aem\$1page\$1lastModified | \$1last\$1updated\$1at | Default | Date |
| aem\$1page\$1lastReplicatedBy | aem\$1page\$1publisher | Custom | String |
| aem\$1page\$1lastReplicatedAt | aem\$1page\$1publishedAt | Custom | Date |
# IAM role for Amazon Q AEM (Cloud) connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Understand error codes in the AEM (Cloud) connector
Error Codes
The following table provides information about error codes you may see for the AEM (Cloud) connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| AEM-5001 | Error while getting Administrators group. Below are the possible reasons for this error: Provided AEM host URL might be wrong. Provided username and password are invalid or user is non-admin user. | Check whether provided username and password are correct or not. Also ensure that the provided user is either admin or belongs to administrators’ group. |
| AEM-5002 | Error while generating OAuth2 access token. | Provide valid OAuth2 credentials. |
| AEM-5103 | Null/empty AEM host URL. | AEM host URL should not be null or empty. |
| AEM-5104 | Error while parsing https response. Below are the possible reasons for this error. 1. Provided AEM host URL might be wrong, please cross-check the AEM host URL. 2. AEM server is down or not reachable. | Provide a valid host URL, or try again later. |
| AEM-5105 | Provided authType is incorrect. | Auth type should be Basic or OAuth2. |
| AEM-5106 | Null/empty AEM username. | Username should not be null or empty value. |
| AEM-5107 | Null/empty AEM password. | Password should not be null or empty value. |
| AEM-5108 | Null/empty client id. | Client Id should not be null or empty value. |
| AEM-5109 | Null/empty client secret. | Client Secret should not be null or empty value. |
| AEM-5110 | Null/empty private key. | Private key should not be null or empty value. |
| AEM-5111 | Null/empty Page Index field name. | Page index field should not be null or empty value |
| AEM-5112 | Null/empty Page data source field name. | Page data source field should not be null or empty value. |
| AEM-5113 | Null/empty asset Index field name. | Asset index field should not be null or empty value. |
| AEM-5114 | Null/empty asset data source field name. | Asset data source field should not be null or empty value. |
| AEM-5115 | Null/empty crawl type. | crawl Type value should be FULL\$1CRAWL/CHANG\$1LOG type. |
| AEM-5116 | Invalid AEM host URL format. | Check whether provided AEM URL is in correct format or not e.g. http{
"aemUrl": "Adobe Experience Manager On-Premise host URL",
"username": "username with admin permissions",
"password": "password with admin permissions"
} If using OAuth 2.0 authentication for AEM On-Premise: {
"aemUrl": "Adobe Experience Manager host URL",
"clientId": "client ID",
"clientSecret": "client secret",
"privateKey": "private key"
} If using OAuth 2.0 authentication for AEM as a Cloud Service: {
"clientId": "client ID",
"clientSecret": "client secret",
"privateKey": "private key",
"orgId": "organization ID",
"technicalAccountId": "technical account ID",
"imsHost": "Adobe Identity Management System (IMS) host"
} |
| version | The version of this template that's currently supported. |
# How Amazon Q Business connector crawls AEM (Server) ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an AEM (Server) data source to Amazon Q Business, Amazon Q crawls ACL information attached to a document (user and group information) from your AEM (Server) instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
The group and user IDs are mapped as follows:
+ `_group_ids` – Group IDs exist in Adobe Experience Manager content where there are set access permissions. They're mapped from the names of the groups in AEM.
+ `_user_id` – User IDs exist in Adobe Experience Manager content where there are set access permissions. They're mapped from the user emails as the IDs in AEM.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# AEM (Server) data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application environment and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes-types.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Adobe Experience Manager (AEM) connector supports the following entities and the associated reserved and custom attributes.
**Important**
If you map any AEM (Server) field to Amazon Q document title and document body fields, Amazon Q will generate responses from data in the document title and body.
**Topics**
+ [
## Pages
](#aem-field-mappings-pages)
+ [
## Assets
](#aem-field-mappings-assets)
## Pages
Amazon Q supports crawling [AEM Pages](https://experienceleague.adobe.com/docs/experience-manager-65/content/sites/authoring/essentials/page-authoring.html?lang=en) and offers the following page field mappings.
| Adobe Experience Manager (AEM) field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| aem\$1page\$1source\$1uri | \$1source\$1uri | Default | String |
| aem\$1page\$1createdBy | \$1authors | Default | String list |
| aem\$1page\$1template | aem\$1page\$1template | Custom | String |
| aem\$1entity\$1type | \$1category | Default | String |
| aem\$1page\$1createdAt | \$1created\$1at | Default | Date |
| aem\$1page\$1lastModified | \$1last\$1updated\$1at | Default | Date |
| aem\$1page\$1lastReplicatedBy | aem\$1page\$1publisher | Custom | String |
| aem\$1page\$1lastReplicatedAt | aem\$1page\$1publishedAt | Custom | Date |
## Assets
Amazon Q supports crawling [AEM Assets](https://experienceleague.adobe.com/docs/experience-manager-65/content/assets/assets.html?lang=en) and offers the following asset field mappings.
| Adobe Experience Manager (AEM) field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| aem\$1page\$1source\$1uri | \$1source\$1uri | Default | String |
| aem\$1page\$1createdBy | \$1authors | Default | String list |
| aem\$1entity\$1type | \$1category | Default | String |
| aem\$1page\$1createdAt | \$1created\$1at | Default | Date |
| aem\$1page\$1lastModified | \$1last\$1updated\$1at | Default | Date |
| aem\$1page\$1lastReplicatedBy | aem\$1page\$1publisher | Custom | String |
| aem\$1page\$1lastReplicatedAt | aem\$1page\$1publishedAt | Custom | Date |
# IAM role for AEM (Server) connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Understand error codes in the AEM (Server) connector
Error Codes
The following table provides information about error codes you may see for the AEM (Server) connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| AEM-5001 | Error while getting Administrators group. Below are the possible reasons for this error: Provided AEM host URL might be wrong. Provided username and password are invalid or user is non-admin user. | Check whether provided username and password are correct or not. Also ensure that the provided user is either admin or belongs to administrators’ group. |
| AEM-5002 | Error while generating OAuth2 access token. | Provide valid OAuth2 credentials. |
| AEM-5103 | Null/empty AEM host URL. | AEM host URL should not be null or empty. |
| AEM-5104 | Error while parsing https response. Below are the possible reasons for this error. 1. Provided AEM host URL might be wrong, please cross-check the AEM host URL. 2. AEM server is down or not reachable. | Provide a valid host URL, or try again later. |
| AEM-5105 | Provided authType is incorrect. | Auth type should be Basic or OAuth2. |
| AEM-5106 | Null/empty AEM username. | Username should not be null or empty value. |
| AEM-5107 | Null/empty AEM password. | Password should not be null or empty value. |
| AEM-5108 | Null/empty client id. | Client Id should not be null or empty value. |
| AEM-5109 | Null/empty client secret. | Client Secret should not be null or empty value. |
| AEM-5110 | Null/empty private key. | Private key should not be null or empty value. |
| AEM-5111 | Null/empty Page Index field name. | Page index field should not be null or empty value |
| AEM-5112 | Null/empty Page data source field name. | Page data source field should not be null or empty value. |
| AEM-5113 | Null/empty asset Index field name. | Asset index field should not be null or empty value. |
| AEM-5114 | Null/empty asset data source field name. | Asset data source field should not be null or empty value. |
| AEM-5115 | Null/empty crawl type. | crawl Type value should be FULL\$1CRAWL/CHANG\$1LOG type. |
| AEM-5116 | Invalid AEM host URL format. | Check whether provided AEM URL is in correct format or not e.g. http{
"username": "username",
"password": "password"
} If using OAuth 2.0 authentication: {
"clientId": "client ID",
"clientSecret": "client secret",
"tokenUrl": "token URL"
} |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/alfresco-cloud-api.html) |
| enableIdentityCrawler | true to use the Amazon Q identity crawler to sync identity/principal information on users and groups with access to certain documents. Amazon Q Business crawls identity information from your data source to ensure responses are generated only from documents end users have access to by default. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). |
| version | The version of this template that's currently supported. |
# How Amazon Q Business connector crawls Alfresco (Cloud) ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an Alfresco (Cloud) data source to Amazon Q Business, Amazon Q crawls ACL information attached to a document (user and group information) from your Alfresco (Cloud) instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
The group and user IDs are mapped as follows:
+ `_group_ids` – Group IDs exist in Alfresco on files where there are set access permissions. They're mapped from the system names of the groups (not display names) in Alfresco.
+ `_user_id` – User IDs exist in Alfresco on files where there are set access permissions. They're mapped from the user emails as the IDs in Alfresco.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Alfresco (Cloud) data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application environment and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes-types.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Alfresco connector supports the following entities and the associated reserved and custom attributes.
**Important**
If you map any Alfresco (Cloud) field to Amazon Q document title and document body fields, Amazon Q will generate responses from data in the document title and body.
**Topics**
+ [
## Documents
](#alfresco-field-mappings-documents)
+ [
## Comments
](#alfresco-field-mappings-comments)
## Documents
| Alfresco field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| creationTime | \$1created\$1at | Default | Date |
| lastModified | \$1last\$1updated\$1at | Default | Date |
| author | \$1authors | Default | String list |
| sourceUri | \$1source\$1uri | Default | String |
| category | \$1category | Default | String |
| fileType | \$1file\$1type | Default | String |
| version | \$1version | Default | String |
| siteName | al\$1site\$1name | Custom | String |
| size | al\$1document\$1size | Custom | Long (numeric) |
| versionType | al\$1version\$1type | Custom | String |
| title | al\$1document\$1title | Custom | String |
| repositoryId | al\$1repository\$1id | Custom | String |
## Comments
| Alfresco field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| creationTime | \$1created\$1at | Default | Date |
| lastModified | \$1last\$1updated\$1at | Default | Date |
| author | \$1authors | Default | String list |
| sourceUri | \$1source\$1uri | Default | String |
| version | \$1version | Default | String |
| category | \$1category | Default | String |
| fileType | \$1file\$1type | Default | String |
| siteName | al\$1site\$1name | Custom | String |
| size | al\$1document\$1size | Custom | Long (numeric) |
| versionType | \$1al\$1version\$1type | Custom | String |
| title | al\$1document\$1title | Custom | String |
| repositoryId | al\$1repository\$1id | Custom | String |
# IAM role for Alfresco (Cloud) connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Alfresco (Server) to Amazon Q Business
Alfresco (Server)
**Note**
Alfresco (Server) connector remains fully supported for existing customers through May 31, 2026. While this connector is no longer available for new users, current users can continue to use it without interruption. We are continuously evolving our connector portfolio to offer more scalable and customizable solutions. For future integrations, we recommend exploring the [Amazon Q Business Custom Connector Framework](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-connector.html), designed to support a broader range of enterprise use cases with enhanced flexibility.
Alfresco is a content management service (CMS) that helps customers store and manage their content. You can connect Alfresco (Server) instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# Alfresco (Server) connector overview
](alfresco-server-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Alfresco (Server)
](alfresco-server-prereqs.md)
+ [
# Connecting Amazon Q Business to Alfresco (Server) using the console
](alfresco-server-console.md)
+ [
# Connecting Amazon Q Business to Alfresco (Server) using APIs
](alfresco-server-api.md)
+ [
# How Amazon Q Business connector crawls Alfresco (Server) ACLs
](alfresco-server-user-management.md)
+ [
# Amazon Q Business Alfresco (Server) data source connector field mappings
](alfresco-server-field-mappings.md)
+ [
# IAM role for Amazon Q Business Alfresco (Server) connector
](alfresco-server-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Alfresco (Server) connector overview
Overview
The following table gives an overview of the Amazon Q Business Alfresco (Server) connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/alfresco-server-overview.html)
# Prerequisites for connecting Amazon Q Business to Alfresco (Server)
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Alfresco, make sure you have:**
+ Copied your Alfresco repository URL and web application URL. If you only want to index a specific Alfresco site, then also copy the site ID.
+ Noted your Alfresco authentication credentials, which include a username and password with at least read permissions. If you want to use OAuth 2.0 authentication, you should add the user to the Alfresco administrators group.
+ **Optional**: Generated OAuth 2.0 credentials in Alfresco. The credentials include client ID, client secret, and token URL. For more information about how to configure clients for Alfresco On-Premises, see [Alfresco documentation](https://docs.alfresco.com/identity-service/latest/tutorial/sso/saml/). If you use Alfresco Cloud (PaaS), you must contact [Hyland support](https://community.hyland.com/) for Alfresco OAuth 2.0 authentication.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Alfresco (Server) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Alfresco (Server) using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Alfresco (Server) using the AWS Management Console.
**Connecting Amazon Q to Alfresco (Server)**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Alfresco** data source to your Amazon Q application.
1. Then, on the **Alfresco (Server)** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. **Source** – Choose **Alfresco server**.
1. **Alfresco repository URL** – Enter your Alfresco repository URL. For example, if you use Alfresco Cloud (PaaS), the repository URL could be *https://company.alfrescocloud.com*.
1. **Alfresco user application URL** – Enter your Alfresco user interface URL. You can get the repository URL from your Alfresco administrator. For example, the user interface URL could be *https://example.com*.
1. **SSL certificate location** – Enter the path to an SSL certificate file stored in an Amazon S3 bucket.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. **Authentication** – Choose **Basic authentication** or **OAuth 2.0 authentication**. Then choose an existing Secrets Manager secret or create a new secret to store your Alfresco credentials. If you choose to create a new secret, an AWS Secrets Manager secret window opens.
If you chose **Basic authentication**, enter a name for the secret, the Alfresco username, and password.
If you chose **OAuth 2.0 authentication**, enter a name for the secret, client ID, client secret, and token URL.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **Identity crawler** – Amazon Q crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/alfresco-server-connector.html#alfresco-server-iam).
1. In **Sync scope**, enter the following information:
1. **Content** – Choose whether to crawl content marked with 'Aspects' in Alfresco, content within a specific Alfresco site, or content across all your Alfresco sites.
1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB.
1. **Additional configuration – *optional*** – Set the following settings:
+ **Include comments** – Choose to include comments in Alfresco Document library and Blog.
+ **Regex patterns** – Regular expression patterns to include or exclude certain files.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Alfresco (Server) using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
## Alfresco JSON schema
The following is the Alfresco JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"siteId": {
"type": "string"
},
"repoUrl": {
"type": "string"
},
"webAppUrl": {
"type": "string"
},
"repositoryAdditionalProperties": {
"type": "object",
"properties": {
"authType": {
"type": "string",
"enum": [
"OAuth2",
"Basic"
]
},
"type": {
"type": "string",
"enum": [
"PAAS",
"ON_PREM"
]
},
"crawlType": {
"type": "string",
"enum": [
"ASPECT",
"SITE_ID",
"ALL_SITES"
]
}
}
}
}
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"document": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE",
"STRING_LIST",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE",
"STRING_LIST",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"type": "boolean"
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"aspectName": {
"type": "string"
},
"aspectProperties": {
"type": "array"
},
"enableFineGrainedControl": {
"type": "boolean"
},
"isCrawlComment": {
"type": "boolean"
},
"inclusionFileNamePatterns": {
"type": "array"
},
"exclusionFileNamePatterns": {
"type": "array"
},
"inclusionFileTypePatterns": {
"type": "array"
},
"exclusionFileTypePatterns": {
"type": "array"
},
"inclusionFilePathPatterns": {
"type": "array"
},
"exclusionFilePathPatterns": {
"type": "array"
}
}
},
"type": {
"type": "string",
"pattern": "ALFRESCO"
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL"
]
},
"enableIdentityCrawler": {
"type": "boolean"
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties",
"type",
"secretArn"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | The endpoint information for the data source. |
| siteId | The identifier of the Alfresco site. |
| repoUrl | The URL of your Alfresco repository. You can get the repository URL from your Alfresco administrator. For example, if you use Alfresco Cloud (PaaS), the repository URL could be https://company.alfrescocloud.com. Or, if you use Alfresco On-Premises, the repository URL could be https://company-alfresco-instance.company-domain.suffix:port. |
| webAppUrl | The URL of your Alfresco user interface. You can get the Alfresco user interface URL from your Alfresco administrator. For example, the user interface URL could be https://example.com. |
| repositoryAdditionalProperties | Additional properties for content in your data source. |
| maxFileSizeInMegaBytes | Specify the Maximum file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. |
| isCrawlAcl | Specify true to crawl access control information from documents. Amazon Q Business crawls ACL information to ensure responses are generated only from documents your end users have access to by default. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. |
| fieldForUserId | Specify field to use for UserId for ACL crawling. |
| authType | The type of authentication that you use, whether OAuth2 or Basic. |
| type (deployment) | The type of Alfresco that you use, whether PAAS or ON-PREM. |
| crawlType | The type of content that you want to crawl, whether ASPECT (content marked with 'Aspects' in Alfresco), SITE\$1ID (content within a specific Alfresco site), or ALL\$1SITES (content across all your Alfresco sites). |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/alfresco-server-api.html) | A list of objects that map the attributes or field names of your Alfresco documents and comments to Amazon Q index field names. |
| additionalProperties | Additional configuration options for your content in your data source. |
| aspectProperties | A list of specific 'Aspects' content that you want to index. |
| enableFineGrainedControl | `true` to crawl 'Aspects'. |
| isCrawlComment | `true` to index comments. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/alfresco-server-api.html) | A list of regular expression patterns to include certain files in your Alfresco data source. Files that match the patterns are included in the index. Files that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/alfresco-server-api.html) | A list of regular expression patterns to exclude certain files in your Alfresco data source. Files that match the patterns are excluded from the index. Files that don't match the patterns are included in the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. |
| type | The type of data source. Specify ALFRESCO as your data source type. |
| secretArn | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs that are required to connect to your Alfresco. The secret must contain a JSON structure with the following keys: If using basic authentication: {
"username": "username",
"password": "password"
} If using OAuth 2.0 authentication: {
"clientId": "client ID",
"clientSecret": "client secret",
"tokenUrl": "token URL"
} |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/alfresco-server-api.html) |
| enableIdentityCrawler | true to use the Amazon Q identity crawler to sync identity/principal information on users and groups with access to certain documents. Amazon Q Business crawls identity information from your data source to ensure responses are generated only from documents end users have access to by default. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). |
| version | The version of this template that's currently supported. |
# How Amazon Q Business connector crawls Alfresco (Server) ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an Alfresco (Server) data source to Amazon Q Business, Amazon Q crawls ACL information attached to a document (user and group information) from your Alfresco (Server) instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
The group and user IDs are mapped as follows:
+ `_group_ids` – Group IDs exist in Alfresco on files where there are set access permissions. They're mapped from the system names of the groups (not display names) in Alfresco.
+ `_user_id` – User IDs exist in Alfresco on files where there are set access permissions. They're mapped from the user emails as the IDs in Alfresco.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Amazon Q Business Alfresco (Server) data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application environment and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes-types.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Alfresco connector supports the following entities and the associated reserved and custom attributes.
**Important**
If you map any Alfresco (Server) field to Amazon Q document title and document body fields, Amazon Q will generate responses from data in the document title and body.
**Topics**
+ [
## Documents
](#alfresco-field-mappings-documents)
+ [
## Comments
](#alfresco-field-mappings-comments)
## Documents
| Alfresco field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| creationTime | \$1created\$1at | Default | Date |
| lastModified | \$1last\$1updated\$1at | Default | Date |
| author | \$1authors | Default | String list |
| sourceUri | \$1source\$1uri | Default | String |
| category | \$1category | Default | String |
| fileType | \$1file\$1type | Default | String |
| version | \$1version | Default | String |
| siteName | al\$1site\$1name | Custom | String |
| size | al\$1document\$1size | Custom | Long (numeric) |
| versionType | al\$1version\$1type | Custom | String |
| title | al\$1document\$1title | Custom | String |
| repositoryId | al\$1repository\$1id | Custom | String |
## Comments
| Alfresco field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| creationTime | \$1created\$1at | Default | Date |
| lastModified | \$1last\$1updated\$1at | Default | Date |
| author | \$1authors | Default | String list |
| sourceUri | \$1source\$1uri | Default | String |
| version | \$1version | Default | String |
| category | \$1category | Default | String |
| fileType | \$1file\$1type | Default | String |
| siteName | al\$1site\$1name | Custom | String |
| size | al\$1document\$1size | Custom | Long (numeric) |
| versionType | \$1al\$1version\$1type | Custom | String |
| title | al\$1document\$1title | Custom | String |
| repositoryId | al\$1repository\$1id | Custom | String |
# IAM role for Amazon Q Business Alfresco (Server) connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Aurora (MySQL) to Amazon Q Business
Aurora (MySQL)
**Note**
Aurora (MySQL) connector remains fully supported for existing customers through May 31, 2026. While this connector is no longer available for new users, current users can continue to use it without interruption. We are continuously evolving our connector portfolio to offer more scalable and customizable solutions. For future integrations, we recommend exploring the [Amazon Q Business Custom Connector Framework](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-connector.html), designed to support a broader range of enterprise use cases with enhanced flexibility.
Aurora (MySQL) is a relational database management system (RDBMS) built for the cloud. You can connect your Aurora (MySQL) instance to Amazon Q Business—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
The Amazon Q Aurora (MySQL) data source connector supports Aurora MySQL 3 and Aurora Serverless MySQL 8.0.
**Important**
As a best practice, provide Amazon Q with read-only database credentials. Also, avoid adding tables with sensitive data or personal identifiable information (PII).
**Topics**
+ [
# Known limitations for the Aurora (MySQL) connector
](aurora-mysql-limitations.md)
+ [
# Aurora (MySQL) connector overview
](aurora-mysql-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Aurora (MySQL)
](aurora-mysql-prereqs.md)
+ [
# Connecting Amazon Q Business to Aurora (MySQL) using the console
](aurora-mysql-console.md)
+ [
# Connecting Amazon Q Business to Aurora (MySQL) using APIs
](aurora-mysql-api.md)
+ [
# How Amazon Q Business connector crawls Aurora (MySQL) ACLs
](aurora-mysql-user-management.md)
+ [
# Aurora (MySQL) data source connector field mappings
](aurora-mysql-field-mappings.md)
+ [
# IAM role for Aurora (MySQL) connector
](aurora-mysql-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Aurora (MySQL) connector
Known limitations
The Aurora (MySQL) connector has the following known limitations:
+ Deleted database rows will not be tracked in when Amazon Q checks for updated content.
+ The size of field names and values in a row of your database can't exceed 400KB.
+ Column names should only contain alphanumeric characters and not spaces.
+ If you have a large amount of data in your database data source, and do not want Amazon Q to index all your database content after the first sync, you can choose to sync only new, modified, or deleted documents.
# Aurora (MySQL) connector overview
Overview
The following table gives an overview of the Amazon Q Business Aurora (MySQL) connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/aurora-mysql-overview.html)
# Prerequisites for connecting Amazon Q Business to Aurora (MySQL)
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Aurora (MySQL), make sure you have:**
+ Noted your database username and password.
**Important**
As a best practice, provide Amazon Q with read-only database credentials.
+ Copied your database host URL, port, and instance. You can find this information on the Amazon RDS console.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Aurora (MySQL) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Aurora (MySQL) using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Aurora (MySQL) using the AWS Management Console.
**Connecting Amazon Q to Aurora (MySQL)**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Aurora (MySQL)** data source to your Amazon Q application.
1. Then, on the **Aurora (MySQL)** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
1. **Host** – Enter the database host URL, for example: `http://instance URL.region.rds.amazonaws.com`.
1. **Port** – Enter the database port, for example, `5432`.
1. **Instance** – Enter the database instance, for example `postgres`.
1. **SSL certificate location** – Choose to enter the Amazon S3 path to your SSL certificate file.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. In **Authentication**, enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. For **Database username**, and **Password** – Enter the authentication credential values you copied from your database.
1. Choose **Save**.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/aurora-mysql-connector.html#aurora-mysql-iam).
1. In **Sync scope**, enter the following information:
+ **SQL query** – Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query.
+ **Primary key column** – Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data.
+ **Title column** – Provide the column in your database table that contains the document titles.
+ **Body column** – Provide the column in your database table that contains the document body text.
Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias.
**Important**
Place the entire SQL statement on a single line. For example:
```
SELECT column1, column2, column3 FROM table_name WHERE condition;
```
Queries with line breaks will cause errors.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Additional configuration – *optional*** – Configure the following settings:
+ **Change-detecting columns** – Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns.
+ **Users' IDs column** – Enter the name of the column which contains User IDs to be allowed access to content.
+ **Groups column** – Enter the name of the column that contains groups to be allowed access to content.
+ **Source URLs column** – Enter the name of the column which contains Source URLs to be indexed.
+ **Time stamps column** – Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content.
+ **Time zones column** – Enter the name of the column which contains time zones for the content to be crawled.
+ **Time stamps format** – Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content.
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Aurora (MySQL) using APIs
Using the API
You use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application.
Then, you use the `configuration` parameter to provide a JSON schema with all other configuration information specific to your data source connector.
## Aurora (MySQL) JSON schema
The following is the Aurora (MySQL) JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"dbType": {
"type": "string",
"enum": [
"mysql",
"db2",
"postgresql",
"oracle",
"sqlserver"
]
},
"dbHost": {
"type": "string"
},
"dbPort": {
"type": "string"
},
"dbInstance": {
"type": "string"
}
},
"required": [
"dbType",
"dbHost",
"dbPort",
"dbInstance"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"document": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string"
},
"dataSourceFieldName": {
"type": "string"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
}
},
"required": [
]
},
"additionalProperties": {
"type": "object",
"properties": {
"primaryKey": {
"type": "string"
},
"titleColumn": {
"type": "string"
},
"bodyColumn": {
"type": "string"
},
"sqlQuery": {
"type": "string",
"not": {
"pattern": ";+"
}
},
"timestampColumn": {
"type": "string"
},
"timestampFormat": {
"type": "string"
},
"timezone": {
"type": "string"
},
"changeDetectingColumns": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedUsersColumn": {
"type": "string"
},
"allowedGroupsColumn": {
"type": "string"
},
"sourceURIColumn": {
"type": "string"
},
"serverlessAurora": {
"type": "string",
"enum": ["true", "false"]
}
},
"required": ["primaryKey", "titleColumn", "bodyColumn", "sqlQuery"]
},
"type" : {
"type" : "string",
"pattern": "JDBC"
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL",
"CHANGE_LOG"
]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | Required configuration information for connecting your data source.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/aurora-mysql-api.html) |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. Specify the type of data source and the secret ARN. |
| document | A list of objects that map the attributes or field names of your database content to Amazon Q index field names. For more information, see [Fiel](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings). |
| additionalProperties | Additional configuration options for your content in your data source. Use to include or exclude specific content in your database data source. |
| primaryKey | Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data. |
| titleColumn | Provide the name of the column in your database table that you want to designate as the column with document titles. |
| bodyColumn | Provide the name of the column in your database table that you want to designate as the column with document body text. Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias. |
| sqlQuery | Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query. |
| timestampColumn | Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content. |
| timestampFormat | Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content. |
| timezone | Enter the name of the column which contains time zones for the content to be crawled. |
| changeDetectingColumns | Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns |
| allowedUsersColumns | Enter the name of the column which contains User IDs to be allowed access to content. |
| allowedGroupsColumn | Enter the name of the column which contains User IDs to be allowed access to content. |
| sourceURIColumn | Enter the name of the column which contains Source URLs to be indexed. |
| isSslEnabled | true to add a path to an SSL certificate file stored in an Amazon S3 bucket. |
| type | The type of data source. Specify JDBC as your data source type. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/aurora-mysql-api.html) |
| secretArn | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains username and password required to connect to your database. The secret must contain a JSON structure with the following keys: {
"username": "database username",
"password": "password"
} |
| version | The version of the template that is currently supported. |
# How Amazon Q Business connector crawls Aurora (MySQL) ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect a database data source to Amazon Q, Amazon Q crawls user and group information from a column in the source table. You specify this column in the console or using the `configuration` parameter as part of the `CreateDataSource` operation.
If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
A database data source has the following limitations:
+ You can only specify an allow list for a database data source. You can't specify a deny list.
+ You can only specify groups. You can't specify individual users for the allow list.
+ The database column should be a string containing a semicolon delimited list of groups.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Aurora (MySQL) data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q PostgreSQL connector supports the following field mappings:
**Topics**
+ [
## Document
](#aurora-mysql-field-mappings-document)
## Document
| JDBC field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| jd\$1document\$1id | jd\$1document\$1id | Custom | String |
| jd\$1document\$1title | jd\$1document\$1title | Custom | String |
| jd\$1source\$1uri | \$1source\$1uri | Default | String |
# IAM role for Aurora (MySQL) connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Aurora (PostgreSQL) to Amazon Q Business
Aurora (PostgreSQL)
**Note**
Aurora (PostgreSQL) connector remains fully supported for existing customers through May 31, 2026. While this connector is no longer available for new users, current users can continue to use it without interruption. We are continuously evolving our connector portfolio to offer more scalable and customizable solutions. For future integrations, we recommend exploring the [Amazon Q Business Custom Connector Framework](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-connector.html), designed to support a broader range of enterprise use cases with enhanced flexibility.
Aurora (PostgreSQL) is a relational database management system (RDBMS) built for the cloud. You can connect your Aurora (PostgreSQL) instance to Amazon Q Business—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
The Amazon Q Aurora (PostgreSQL) data source connector supports Aurora PostgreSQL 1.
**Important**
As a best practice, provide Amazon Q with read-only database credentials. Also, avoid adding tables with sensitive data or personal identifiable information (PII).
**Topics**
+ [
# Known limitations for the Aurora (PostgreSQL) connector
](aurora-postgresql-limitations.md)
+ [
# Aurora (PostgreSQL) connector overview
](aurora-postgresql-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Aurora (PostgreSQL)
](aurora-postgresql-prereqs.md)
+ [
# Connecting Amazon Q Business to Aurora (PostgreSQL) using the console
](aurora-postgresql-console.md)
+ [
# Connecting Amazon Q Business to Aurora (PostgreSQL) using APIs
](aurora-postgresql-api.md)
+ [
# How Amazon Q Business connector crawls Aurora (PostgreSQL) ACLs
](aurora-postgresql-user-management.md)
+ [
# Aurora (PostgreSQL) data source connector field mappings
](aurora-postgresql-field-mappings.md)
+ [
# IAM role for Aurora (PostgreSQL) connector
](aurora-postgresql-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Aurora (PostgreSQL) connector
Known limitations
The Aurora (PostgreSQL) connector has the following known limitations:
+ Deleted database rows will not be tracked in when Amazon Q checks for updated content.
+ The size of field names and values in a row of your database can't exceed 400KB.
+ Column names should only contain alphanumeric characters and not spaces.
+ If you have a large amount of data in your database data source, and do not want Amazon Q to index all your database content after the first sync, you can choose to sync only new, modified, or deleted documents.
# Aurora (PostgreSQL) connector overview
Overview
The following table gives an overview of the Amazon Q Business Aurora (PostgreSQL) connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/aurora-postgresql-overview.html)
# Prerequisites for connecting Amazon Q Business to Aurora (PostgreSQL)
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Aurora (PostgreSQL), make sure you have:**
+ Noted your database username and password.
**Important**
As a best practice, provide Amazon Q with read-only database credentials.
+ Copied your database host URL, port, and instance. You can find this information on the Amazon RDS console.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Aurora (PostgreSQL) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Aurora (PostgreSQL) using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Aurora (PostgreSQL) using the AWS Management Console.
**Connecting Amazon Q to Aurora (PostgreSQL)**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Aurora (PostgreSQL)** data source to your Amazon Q application.
1. Then, on the **Aurora (PostgreSQL)** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
1. **Host** – Enter the database host URL, for example: `http://instance URL.region.rds.amazonaws.com`.
1. **Port** – Enter the database port, for example, `5432`.
1. **Instance** – Enter the database instance
1. **Enable SSL certificate location** – Choose to enter the Amazon S3 path to your SSL certificate file.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. In **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. For **Database username**, and **Password** – Enter the authentication credential values you copied from your database.
1. Choose **Save**.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/aurora-postgresql-connector.html#aurora-postgresql-iam).
1. In **Sync scope**, enter the following information:
+ **SQL query** – Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query.
+ **Primary key column** – Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data.
+ **Title column** – Provide the name of the column in your database table that you want to designate as the column with document titles.
+ **Body column** – Provide the name of the column in your database table that you want to designate as the column with document body text.
Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Additional configuration – *optional*** – Configure the following settings:
+ **Change-detecting columns** – Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns.
+ **Users' IDs column** – Enter the name of the column which contains User IDs to be allowed access to content.
+ **Groups column** – Enter the name of the column that contains groups to be allowed access to content.
+ **Source URLs column** – Enter the name of the column which contains Source URLs to be indexed.
+ **Time stamps column** – Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content.
+ **Time zones column** – Enter the name of the column which contains time zones for the content to be crawled.
+ **Time stamps format** – Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content.
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Aurora (PostgreSQL) using APIs
Using the API
You use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application.
Then, you use the `configuration` parameter to provide a JSON schema with all other configuration information specific to your data source connector.
## Aurora (PostgreSQL) JSON schema
The following is the Aurora (PostgreSQL) JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"dbType": {
"type": "string",
"enum": [
"mysql",
"db2",
"postgresql",
"oracle",
"sqlserver"
]
},
"dbHost": {
"type": "string"
},
"dbPort": {
"type": "string"
},
"dbInstance": {
"type": "string"
}
},
"required": [
"dbType",
"dbHost",
"dbPort",
"dbInstance"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"document": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string"
},
"dataSourceFieldName": {
"type": "string"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
}
},
"required": [
]
},
"additionalProperties": {
"type": "object",
"properties": {
"primaryKey": {
"type": "string"
},
"titleColumn": {
"type": "string"
},
"bodyColumn": {
"type": "string"
},
"sqlQuery": {
"type": "string",
"not": {
"pattern": ";+"
}
},
"timestampColumn": {
"type": "string"
},
"timestampFormat": {
"type": "string"
},
"timezone": {
"type": "string"
},
"changeDetectingColumns": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedUsersColumn": {
"type": "string"
},
"allowedGroupsColumn": {
"type": "string"
},
"sourceURIColumn": {
"type": "string"
},
"serverlessAurora": {
"type": "string",
"enum": ["true", "false"]
}
},
"required": ["primaryKey", "titleColumn", "bodyColumn", "sqlQuery"]
},
"type" : {
"type" : "string",
"pattern": "JDBC"
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL",
"CHANGE_LOG"
]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | Required configuration information for connecting your data source.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/aurora-postgresql-api.html) |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. Specify the type of data source and the secret ARN. |
| document | A list of objects that map the attributes or field names of your database content to Amazon Q index field names. For more information, see [Fiel](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings). |
| additionalProperties | Additional configuration options for your content in your data source. Use to include or exclude specific content in your database data source. |
| primaryKey | Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data. |
| titleColumn | Provide the name of the column in your database table that you want to designate as the column with document titles. |
| bodyColumn | Provide the name of the column in your database table that you want to designate as the column with document body text. Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias. |
| sqlQuery | Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query. |
| timestampColumn | Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content. |
| timestampFormat | Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content. |
| timezone | Enter the name of the column which contains time zones for the content to be crawled. |
| changeDetectingColumns | Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns |
| allowedUsersColumns | Enter the name of the column which contains User IDs to be allowed access to content. |
| allowedGroupsColumn | Enter the name of the column which contains User IDs to be allowed access to content. |
| sourceURIColumn | Enter the name of the column which contains Source URLs to be indexed. |
| isSslEnabled | true to add a path to an SSL certificate file stored in an Amazon S3 bucket. |
| type | The type of data source. Specify JDBC as your data source type. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/aurora-postgresql-api.html) |
| secretArn | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains username and password required to connect to your database. The secret must contain a JSON structure with the following keys: {
"username": "database username",
"password": "password"
} |
| version | The version of the template that is currently supported. |
# How Amazon Q Business connector crawls Aurora (PostgreSQL) ACLs
ACL crawling
When you connect a database data source to Amazon Q Business, Amazon Q Business crawls user and group information from a column in the source table. You specify this column in the console or using the `configuration` parameter as part of the `CreateDataSource` operation.
Activating ACL crawling allows the system to filter chat responses based on your end users' document access levels.
Prerequisites:
+ The group ACL column in the database should be a string containing a semicolon delimited list of groups.
+ The user ACL column in the database should be a string containing a semicolon delimited list of users.
A database data source has the following limitation:
+ You can only specify an allow list for a database data source. You can't specify a deny list.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Aurora (PostgreSQL) data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q PostgreSQL connector supports the following field mappings:
**Topics**
+ [
## Document
](#aurora-postgresql-field-mappings-document)
## Document
| JDBC field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| jd\$1document\$1id | jd\$1document\$1id | Custom | String |
| jd\$1document\$1title | jd\$1document\$1title | Custom | String |
| jd\$1source\$1uri | \$1source\$1uri | Default | String |
# IAM role for Aurora (PostgreSQL) connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Drupal to Amazon Q Business
Drupal
**Note**
Drupal connector remains fully supported for existing customers through May 31, 2026. While this connector is no longer available for new users, current users can continue to use it without interruption. We are continuously evolving our connector portfolio to offer more scalable and customizable solutions. For future integrations, we recommend exploring the [Amazon Q Business Custom Connector Framework](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-connector.html), designed to support a broader range of enterprise use cases with enhanced flexibility.
Drupal is an open-source content management system (CMS) that you can use to create websites and web applications. You can connect Drupal instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# Drupal connector overview
](drupal-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Drupal
](drupal-prereqs.md)
+ [
# Connecting Amazon Q Business to Drupal using the console
](drupal-console.md)
+ [
# Connecting Amazon Q Business to Drupal using APIs
](drupal-api.md)
+ [
# How Amazon Q Business connector crawls Drupal ACLs
](drupal-user-management.md)
+ [
# Drupal data source connector field mappings
](drupal-field-mappings.md)
+ [
# IAM role for Drupal connector
](drupal-iam-role.md)
+ [
# Known limitations for the Drupal connector
](drupal-limitations.md)
+ [
# Understand error codes in the Drupal connector
](drupal-error-codes.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Drupal connector overview
Overview
The following table gives an overview of the Amazon Q Business Drupal connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/drupal-overview.html)
# Prerequisites for connecting Amazon Q Business to Drupal
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Drupal, make sure you have:**
+ Created a Drupal (Standard) Suite account and a user with an administrator role.
+ Install the *Web Services* modules from Drupal's core modules. These include the *HTTP Basic Authentication module*, the *JSON:API* module, the *RESTful Web Services* module, and the *Serialization* module.
+ Configure the *JSON:API* module to accept the JSON:API *create*, *read*, *update*, and *delete* operations.
+ Copied your Drupal site name and configured a host URL. For example, *https://{
"user name": "user name",
"passwords": "password"
} **If using OAuth 2.0 authentication:**{
"Client ID": "client_id",
"Client secret": "client_secret",
"user name": "user name",
"password": "password"
} |
| version | The version of this template that is currently supported. |
# How Amazon Q Business connector crawls Drupal ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an Drupal data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your Drupal instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
Amazon Q gets the user and group information from the Drupal instance.The group and user IDs are mapped as follows:
+ `_group_ids` – Group IDs exist in Drupal on files where there are set access permissions. They are mapped from the names of the groups in Drupal.
+ `_user_id` – User IDs exist in Drupal on files where there are set access permissions. They are mapped from the user emails as the IDs in Drupal.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Drupal data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Drupal connector supports the following entities and the associated reserved and custom attributes.
**Topics**
+ [
## Contents
](#drupal-field-mappings-contents)
+ [
## Comments
](#drupal-field-mappings-comments)
+ [
## Attachments
](#drupal-field-mappings-attachments)
## Contents
| Drupal field name | Index field name | Entity | Category | Field type |
| --- | --- | --- | --- | --- |
| title | dpl\$1title | All Entities | Default | String |
| sourceUrl | dpl\$1source\$1url | All Entities | Default | String |
| createdAt | dpl\$1created\$1date | All Entities | Default | Date |
| updatedAt | dpl\$1updated\$1date | All Entities | Default | Date |
| published | dpl\$1published | All Entities | Default | String |
| tag | dpl\$1tag | All Entities | Default | String |
| author | dpl\$1author | All Entities | Default | String |
| category | dpl\$1category | All Entities | Default | String |
| visibility | dpl\$1visibility | All Entities | Default | String |
| viewId | dpl\$1view\$1id | All Entities | Default | String |
## Comments
| Drupal field name | Index field name | Entity | Category | Field type |
| --- | --- | --- | --- | --- |
| title | dpl\$1comment\$1title | All Entities | Default | String |
| sourceUrl | dpl\$1source\$1url | All Entities | Default | String |
| createdAt | dpl\$1created\$1date | All Entities | Default | Date |
| updatedAt | dpl\$1updated\$1date | All Entities | Default | Date |
| approvedStatus | dpl\$1status | All Entities | Default | String |
| author | dpl\$1author | All Entities | Default | String |
| category | dpl\$1category | All Entities | Default | String |
| parentEntityId | dpl\$1parent\$1entity\$1id | All Entities | Default | String |
| visibility | dpl\$1visibility | All Entities | Default | String |
| viewId | dpl\$1view\$1id | All Entities | Default | String |
## Attachments
| Drupal field name | Index field name | Entity | Category | Field type |
| --- | --- | --- | --- | --- |
| fileName | dpl\$1file\$1name | All Entities | Default | String |
| sourceUrl | dpl\$1source\$1url | All Entities | Default | String |
| createdAt | dpl\$1created\$1date | All Entities | Default | Date |
| updatedAt | dpl\$1updated\$1date | All Entities | Default | Date |
| status | dpl\$1status | All Entities | Default | String |
| fileType | dpl\$1file\$1type | All Entities | Default | String |
| fileSize | dpl\$1file\$1size | All Entities | Default | String |
| fileUploadedBy | dpl\$1file\$1uploaded\$1by | All Entities | Default | String |
| category | dpl\$1category | All Entities | Default | String |
| parentEntityId | dpl\$1parent\$1entity\$1id | All Entities | Default | String |
| visibility | dpl\$1visibility | All Entities | Default | String |
| viewId | dpl\$1view\$1id | All Entities | Default | String |
# IAM role for Drupal connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Known limitations for the Drupal connector
Known limitations
Amazon Q Business Drupal connector has the following known limitations:
+ Drupal APIs have no official throttling limits.
+ Java SDKs are not available for Drupal.
+ Drupal data can be fetched only using native JSON API’s.
+ Content types not associated with any Drupal **View** cannot be crawled.
+ You need administrator access to crawl data from Drupal **Blocks**.
+ There is no JSON API available to create the user defined content type using HTTP verbs.
+ The document body and comments for **Articles**, **Basic pages**, **Basic blocks**, user defined content type, and user defined block type, are displayed in HTML format. If the HTML content is not well-formed, then the HTML related tags will appear in the document body and comments and will be visible in Amazon Kendra search results.
+ Content types and **Block** types without description or body will not be ingested into Amazon Q. Only **Comments** and **Attachments** of such **Content** or **Block** types will be ingested into your Amazon Q index.
# Understand error codes in the Drupal connector
Error Codes
The following table provides information about error codes you may see for the Drupal connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| DPL-5001 | Invalid userName or password while validating credentials. | Provide valid values for the userName and password. |
| DPL-5002 | Invalid userName or password while validating OAuth credentials. | Provide valid userName and password. |
| DPL-5003 | Invalid clientId or clientSecret while validating OAuth credentials. | Provide valid clientId and clientSecret. |
| DPL-5100 | Empty/null host URL | The hostUrl should not be null or empty. |
| DPL-5101 | Null/empty username. | Provide a valid userName. |
| DPL-5102 | Null/empty password. | Provide a valid password. |
| DPL-5103 | Null/empty ClientId. | Provide a valid clientId. |
| DPL-5104 | Null/empty Client Secret. | Provide a valid clientSecret. |
| DPL-5105 | Incorrect auth type in the repositoryAdditionalProperties. | The authType should be basicAuth or OAuth2. |
| DPL-5106 | Null/empty auth type in the repositoryAdditionalProperties. | The authType should not be null or empty. |
| DPL-5107 | Null/empty Repository Configurations. | The repositoryConfigurations should not be null or empty. |
| DPL-5108 | Only String, String List, Date and Long formats are supported for the indexFieldType in all the field mappings. | Provide the supported format only for the indexFieldType in all the fieldMappings. |
| DPL-5109 | Not able to read the file from the S3 bucket location. | Check if valid JSON file is provided in the repositoryAdditionalProperties. |
| DPL-5110 | Invalid Profile Name provided. | Provide a valid s3ProfileName in the repositoryAdditionalProperties. For example, default |
| DPL-5111 | Null/empty Profile Name. | The s3ProfileName should not be null/empty in the repositoryAdditionalProperties. |
| DPL-5112 | Invalid URI found during address validation. | Provide a valid hostUrl. |
| DPL-5131 | Null/empty ContentTypes/BlockTypes in contentDefinitions. | Provide value for the contentType or blockType in contentDefinitions. |
| DPL-5132 | Null/empty/unknown field definitions in the contentDefinitions. | The fieldDefinition should be an empty array only. |
| DPL-5133 | Invalid field definitions in the contentDefinitions. | In the contentDefinitions, the fieldDefinition should be a json array only having machineName and type fields. |
| DPL-5134 | Null/empty value found for the machineName in the fieldDefinition. | Provide value for the machineName in the fieldDefinition. |
| DPL-5135 | Null/empty value found for the type in the fieldDefinition. | Provide value for the type in the fieldDefinition. |
| DPL-5136 | Invalid isCrawlComments value. | isCrawlComments should be a boolean value true or false. |
| DPL-5137 | Invalid isCrawlFiles value. | isCrawlFiles should be a boolean value true or false. |
| DPL-5138 | The machineName is not found in the fieldDefinition. | Define the machineName as key in the fieldDefinition. |
| DPL-5139 | The type is not found in the fieldDefinition. | Define the type as key in the fieldDefinition. |
| DPL-5151 | Invalid inclusion file name patterns | Provide valid regex pattern in the inclusionFileNamePatterns. |
| DPL-5152 | Invalid exclusion file name patterns. | Provide valid regex pattern in the exclusionFileNamePatterns. |
| DPL-5153 | Invalid Article title inclusion patterns. | Provide valid regex pattern in the articleTitleInclusionPatterns. |
| DPL-5154 | Invalid Article title exclusion patterns. | Please provide valid regex pattern in the articleTitleExclusionPatterns. |
| DPL-5155 | Invalid Page title inclusion filter patterns. | Provide valid regex pattern in the pageTitleInclusionPatterns. |
| DPL-5156 | Invalid Page title exclusion filter patterns. | Provide valid regex pattern in the pageTitleExclusionPatterns. |
| DPL-5157 | Invalid Custom Content title inclusion filter patterns. | Provide valid regex pattern in the customContentTitleInclusionPatterns. |
| DPL-5158 | Invalid Custom Content title exclusion filter patterns. | Provide valid regex pattern in the customContentTitleExclusionPatterns. |
| DPL-5159 | Invalid Basic Block title inclusion filter patterns. | Provide valid regex pattern in the basicBlockTitleInclusionPatterns. |
| DPL-5160 | Invalid Basic Block title exclusion filter patterns. | Provide valid regex pattern in the basicBlockTitleExclusionPatterns. |
| DPL-5161 | Invalid Custom Block title inclusion filter patterns. | Provide valid regex pattern in the customBlockTitleInclusionPatterns. |
| DPL-5162 | Invalid Custom Block title exclusion filter patterns. | Provide valid regex pattern in the customBlockTitleExclusionPatterns. |
| DPL-5200 | IO Exception occurred while reading contents from Drupal. | Refer to the log for more details. |
| DPL-5201 | Please try again later. Unknown exception occurred. | Unknown exception occurred. Refer to the log for more details. |
| DPL-5202 | Issue occurred while initializing Views with acl info in the cache for content entity: | Issue with Views. Refer to the log for more details. |
| DPL-5203 | Drupal Configuration found null during change access token of OAuth authentication. | Issue with OAuth Authentication. Refer to the log for more details. |
| DPL-5204 | The generated access token is empty or null. Issue occurred while generating access token. | Access token should not be null/empty. Provide valid access token and try. If still issue exists, refer to the log for more details. |
| DPL-5205 | User info with the given userName do not exist. | Verify the provided userName and correct it. |
| DPL-5206 | The api response has empty data element. | Check the logs for details about empty response body. |
| DPL-5207 | Either no records found or some issue with View filter criteria for content entity: | Refer to the log for more details. |
| DPL-5500 | Drupal connection successful. | Drupal connection successful. |
# Connecting IBM DB2 to Amazon Q Business
IBM DB2
**Note**
IBM DB2 connector remains fully supported for existing customers through May 31, 2026. While this connector is no longer available for new users, current users can continue to use it without interruption. We are continuously evolving our connector portfolio to offer more scalable and customizable solutions. For future integrations, we recommend exploring the [Amazon Q Business Custom Connector Framework](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-connector.html), designed to support a broader range of enterprise use cases with enhanced flexibility.
IBM DB2 is a relational database management system developed by IBM. If you are a AWS user, you can use Amazon Q Business to index your IBM DB2 data source.
You can connect your IBM DB2 instance to Amazon Q—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
The Amazon Q IBM DB2 data source connector supports DB2 11.5.7.
**Important**
As a best practice, provide Amazon Q with read-only database credentials. Also, avoid adding tables with sensitive data or personal identifiable information (PII).
**Topics**
+ [
# Known limitations for the IBM DB2 connector
](ibm-db2-limitations.md)
+ [
# IBM DB2 connector overview
](ibm-db2-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to IBM DB2
](ibm-db2-prereqs.md)
+ [
# Connecting Amazon Q Business to IBM DB2 using the console
](ibm-db2-console.md)
+ [
# Connecting Amazon Q Business to IBM DB2 using APIs
](ibm-db2-api.md)
+ [
# How Amazon Q Business connector crawls IBM DB2 ACLs
](ibm-db2-user-management.md)
+ [
# IBM DB2 data source connector field mappings
](ibm-db2-field-mappings.md)
+ [
# IAM role for IBM DB2 connector
](ibm-db2-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the IBM DB2 connector
Known limitations
The IBM DB2 connector has the following known limitations:
+ Deleted database rows will not be tracked in when Amazon Q checks for updated content.
+ The size of field names and values in a row of your database can't exceed 400KB.
+ Column names should only contain alphanumeric characters and not spaces.
+ If you have a large amount of data in your database data source, and do not want Amazon Q to index all your database content after the first sync, you can choose to sync only new, modified, or deleted documents.
# IBM DB2 connector overview
Overview
The following table gives an overview of the IBM DB2 connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/ibm-db2-overview.html)
# Prerequisites for connecting Amazon Q Business to IBM DB2
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In IBM DB2, make sure you have:**
+ Noted your database username and password.
**Important**
As a best practice, provide Amazon Q with read-only database credentials.
+ Copied your database host URL, port, and instance.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your IBM DB2 authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to IBM DB2 using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to IBM DB2 using the AWS Management Console.
**Connecting Amazon Q to IBM DB2**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **IBM DB2** data source to your Amazon Q application.
1. Then, on the **IBM DB2** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
1. **Host** – Enter the database host name.
1. **Port** – Enter the database port.
1. **Instance** – Enter the database instance.
1. **Enable SSL certificate location** – Choose to enter the Amazon S3 path to your SSL certificate file.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. In **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. For **Database username**, and **Password** – Enter the authentication credential values you copied from your database.
1. Choose **Save**.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/ibm-db2-connector.html#ibm-db2-iam).
1. In **Sync scope**, enter the following information:
+ **SQL query** – Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query.
+ **Primary key column** – Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data.
+ **Title column** – Provide the name of the column in your database table that you want to designate as the column with document titles.
+ **Body column** – Provide the name of the column in your database table that you want to designate as the column with document body text.
Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Additional configuration – *optional*** – Configure the following settings:
+ **Change-detecting columns** – Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns.
+ **Users' IDs column** – Enter the name of the column which contains User IDs to be allowed access to content.
+ **Groups column** – Enter the name of the column that contains groups to be allowed access to content.
+ **Source URLs column** – Enter the name of the column which contains Source URLs to be indexed.
+ **Time stamps column** – Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content.
+ **Time zones column** – Enter the name of the column which contains time zones for the content to be crawled.
+ **Time stamps format** – Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content.
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to IBM DB2 using APIs
Using the API
You use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application.
Then, you use the `configuration` parameter to provide a JSON schema with all other configuration information specific to your data source connector.
## IBM DB2 JSON schema
The following is the IBM DB2 JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"dbType": {
"type": "string",
"enum": [
"mysql",
"db2",
"postgresql",
"oracle",
"sqlserver"
]
},
"dbHost": {
"type": "string"
},
"dbPort": {
"type": "string"
},
"dbInstance": {
"type": "string"
}
},
"required": [
"dbType",
"dbHost",
"dbPort",
"dbInstance"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"document": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string"
},
"dataSourceFieldName": {
"type": "string"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
}
},
"required": [
]
},
"additionalProperties": {
"type": "object",
"properties": {
"primaryKey": {
"type": "string"
},
"titleColumn": {
"type": "string"
},
"bodyColumn": {
"type": "string"
},
"sqlQuery": {
"type": "string",
"not": {
"pattern": ";+"
}
},
"timestampColumn": {
"type": "string"
},
"timestampFormat": {
"type": "string"
},
"timezone": {
"type": "string"
},
"changeDetectingColumns": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedUsersColumn": {
"type": "string"
},
"allowedGroupsColumn": {
"type": "string"
},
"sourceURIColumn": {
"type": "string"
},
"serverlessAurora": {
"type": "string",
"enum": ["true", "false"]
}
},
"required": ["primaryKey", "titleColumn", "bodyColumn", "sqlQuery"]
},
"type" : {
"type" : "string",
"pattern": "JDBC"
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL",
"CHANGE_LOG"
]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | Required configuration information for connecting your data source.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/ibm-db2-api.html) |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. Specify the type of data source and the secret ARN. |
| document | A list of objects that map the attributes or field names of your database content to Amazon Q index field names. For more information, see [Fiel](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings). |
| additionalProperties | Additional configuration options for your content in your data source. Use to include or exclude specific content in your database data source. |
| primaryKey | Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data. |
| titleColumn | Provide the name of the column in your database table that you want to designate as the column with document titles. |
| bodyColumn | Provide the name of the column in your database table that you want to designate as the column with document body text. Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias. |
| sqlQuery | Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query. |
| timestampColumn | Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content. |
| timestampFormat | Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content. |
| timezone | Enter the name of the column which contains time zones for the content to be crawled. |
| changeDetectingColumns | Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns |
| allowedUsersColumns | Enter the name of the column which contains User IDs to be allowed access to content. |
| allowedGroupsColumn | Enter the name of the column which contains User IDs to be allowed access to content. |
| sourceURIColumn | Enter the name of the column which contains Source URLs to be indexed. |
| isSslEnabled | true to add a path to an SSL certificate file stored in an Amazon S3 bucket. |
| type | The type of data source. Specify JDBC as your data source type. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/ibm-db2-api.html) |
| secretArn | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains username and password required to connect to your database. The secret must contain a JSON structure with the following keys: {
"username": "database username",
"password": "password"
} |
| version | The version of the template that is currently supported. |
# How Amazon Q Business connector crawls IBM DB2 ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect a database data source to Amazon Q, Amazon Q crawls user and group information from a column in the source table. You specify this column in the console or using the `configuration` parameter as part of the `CreateDataSource` operation.
If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
A database data source has the following limitations:
+ You can only specify an allow list for a database data source. You can't specify a deny list.
+ You can only specify groups. You can't specify individual users for the allow list.
+ The database column should be a string containing a semicolon delimited list of groups.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# IBM DB2 data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q PostgreSQL connector supports the following field mappings:
**Topics**
+ [
## Document
](#ibm-db2-field-mappings-document)
## Document
| JDBC field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| jd\$1document\$1id | jd\$1document\$1id | Custom | String |
| jd\$1document\$1title | jd\$1document\$1title | Custom | String |
| jd\$1source\$1uri | \$1source\$1uri | Default | String |
# IAM role for IBM DB2 connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Microsoft SQL Server to Amazon Q Business
Microsoft SQL Server
**Note**
Microsoft SQL Server connector remains fully supported for existing customers through May 31, 2026. While this connector is no longer available for new users, current users can continue to use it without interruption. We are continuously evolving our connector portfolio to offer more scalable and customizable solutions. For future integrations, we recommend exploring the [Amazon Q Business Custom Connector Framework](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-connector.html), designed to support a broader range of enterprise use cases with enhanced flexibility.
Microsoft SQL Server is an relational database management system (RDBMS) developed by Microsoft. You can connect your Microsoft SQL Server instance to Amazon Q Business—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
The Amazon Q Microsoft SQL Server data source connector supports MS SQL Server 2019.
**Important**
As a best practice, provide Amazon Q with read-only database credentials. Also, avoid adding tables with sensitive data or personal identifiable information (PII).
**Topics**
+ [
# Known limitations for the Microsoft SQL Server connector
](ms-sql-server-limitations.md)
+ [
# Microsoft SQL Server connector overview
](ms-sql-server-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Microsoft SQL Server
](ms-sql-server-prereqs.md)
+ [
# Connecting to Microsoft SQL Server using the console
](ms-sql-server-console.md)
+ [
# Connecting to Microsoft SQL Server using APIs
](ms-sql-server-api.md)
+ [
# How connector crawls Microsoft SQL Server ACLs
](ms-sql-server-user-management.md)
+ [
# Microsoft SQL Server data source connector field mappings
](ms-sql-server-field-mappings.md)
+ [
# IAM role for Microsoft SQL Server connector
](ms-sql-server-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Microsoft SQL Server connector
Known limitations
The Microsoft SQL Server connector has the following known limitations:
+ Deleted database rows will not be tracked in when Amazon Q checks for updated content.
+ The size of field names and values in a row of your database can't exceed 400KB.
+ Column names should only contain alphanumeric characters and not spaces.
+ If you have a large amount of data in your database data source, and do not want Amazon Q to index all your database content after the first sync, you can choose to sync only new, modified, or deleted documents.
# Microsoft SQL Server connector overview
Overview
The following table gives an overview of the Amazon Q Business Microsoft SQL Server connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/ms-sql-server-overview.html)
# Prerequisites for connecting Amazon Q Business to Microsoft SQL Server
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Microsoft SQL Server, make sure you have:**
+ Noted your database username and password.
**Important**
As a best practice, provide Amazon Q with read-only database credentials.
+ Copied your database host URL, port, and instance.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Microsoft SQL Server authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting to Microsoft SQL Server using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Microsoft SQL Server using the AWS Management Console.
**Connecting Amazon Q to Microsoft SQL Server**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Microsoft SQL Server** data source to your Amazon Q application.
1. Then, on the **Microsoft SQL Server** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
1. **Host** – Enter the database host name.
1. **Port** – Enter the database port.
1. **Instance** – Enter the database instance.
1. **Enable SSL certificate location** – Choose to enter the Amazon S3 path to your SSL certificate file.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. In **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. For **Database username**, and **Password** – Enter the authentication credential values you copied from your database.
1. Choose **Save**.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/ms-sql-server-connector.html#ms-sql-server-iam).
1. In **Sync scope**, enter the following information:
+ **SQL query** – Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query.
+ **Primary key column** – Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data.
+ **Title column** – Provide the name of the column in your database table that you want to designate as the column with document titles.
+ **Body column** – Provide the name of the column in your database table that you want to designate as the column with document body text.
Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Additional configuration – *optional*** – Configure the following settings:
+ **Change-detecting columns** – Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns.
+ **Users' IDs column** – Enter the name of the column which contains User IDs to be allowed access to content.
+ **Groups column** – Enter the name of the column that contains groups to be allowed access to content.
+ **Source URLs column** – Enter the name of the column which contains Source URLs to be indexed.
+ **Time stamps column** – Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content.
+ **Time zones column** – Enter the name of the column which contains time zones for the content to be crawled.
+ **Time stamps format** – Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content.
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting to Microsoft SQL Server using APIs
Using the API
You use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application.
Then, you use the `configuration` parameter to provide a JSON schema with all other configuration information specific to your data source connector.
## Microsoft SQL Server JSON schema
The following is the Microsoft SQL Server JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"dbType": {
"type": "string",
"enum": [
"mysql",
"db2",
"postgresql",
"oracle",
"sqlserver"
]
},
"dbHost": {
"type": "string"
},
"dbPort": {
"type": "string"
},
"dbInstance": {
"type": "string"
}
},
"required": [
"dbType",
"dbHost",
"dbPort",
"dbInstance"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"document": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string"
},
"dataSourceFieldName": {
"type": "string"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
}
},
"required": [
]
},
"additionalProperties": {
"type": "object",
"properties": {
"primaryKey": {
"type": "string"
},
"titleColumn": {
"type": "string"
},
"bodyColumn": {
"type": "string"
},
"sqlQuery": {
"type": "string",
"not": {
"pattern": ";+"
}
},
"timestampColumn": {
"type": "string"
},
"timestampFormat": {
"type": "string"
},
"timezone": {
"type": "string"
},
"changeDetectingColumns": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedUsersColumn": {
"type": "string"
},
"allowedGroupsColumn": {
"type": "string"
},
"sourceURIColumn": {
"type": "string"
},
"serverlessAurora": {
"type": "string",
"enum": ["true", "false"]
}
},
"required": ["primaryKey", "titleColumn", "bodyColumn", "sqlQuery"]
},
"type" : {
"type" : "string",
"pattern": "JDBC"
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL"
]
},
"secretArn": {
"type": "string"
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | Required configuration information for connecting your data source.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/ms-sql-server-api.html) |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. Specify the type of data source and the secret ARN. |
| document | A list of objects that map the attributes or field names of your database content to Amazon Q index field names. For more information, see [Mapping data source fields](https://docs.aws.amazon.com/kendra/latest/dg/field-mapping.html). |
| additionalProperties | Additional configuration options for your content in your data source. Use to include or exclude specific content in your database data source. |
| primaryKey | Provide the primary key for the database table. This identifies a table within your database. |
| titleColumn | Provide the name of the document title column within your database table. |
| bodyColumn | Provide the name of the document title column within your database table. |
| sqlQuery | Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query. If a table name has special characters, put it in square brackets "[ ]" in the SQL query. For example: select \$1 from [my-database-table]. |
| timestampColumn | Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content. |
| timestampFormat | Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content. |
| timezone | Enter the name of the column which contains time zones for the content to be crawled. |
| changeDetectingColumns | Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns |
| allowedUsersColumns | Enter the name of the column which contains User IDs to be allowed access to content. |
| allowedGroupsColumn | Enter the name of the column which contains User IDs to be allowed access to content. |
| sourceURIColumn | Enter the name of the column which contains Source URLs to be indexed. |
| isSslEnabled | true to add a path to an SSL certificate file stored in an Amazon S3 bucket. |
| type | The type of data source. Specify JDBC as your data source type. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/ms-sql-server-api.html) |
| secretArn | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains user name and password required to connect to your database. The secret must contain a JSON structure with the following keys: {
"username": "database username",
"password": "password"
} |
| version | The version of the template that is currently supported. |
# How connector crawls Microsoft SQL Server ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect a database data source to Amazon Q, Amazon Q crawls user and group information from a column in the source table. You specify this column in the console or using the `configuration` parameter as part of the `CreateDataSource` operation.
If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
A database data source has the following limitations:
+ You can only specify an allow list for a database data source. You can't specify a deny list.
+ You can only specify groups. You can't specify individual users for the allow list.
+ The database column should be a string containing a semicolon delimited list of groups.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Microsoft SQL Server data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q PostgreSQL connector supports the following field mappings:
**Topics**
+ [
## Document
](#ms-sql-server-field-mappings-document)
## Document
| JDBC field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| jd\$1document\$1id | jd\$1document\$1id | Custom | String |
| jd\$1document\$1title | jd\$1document\$1title | Custom | String |
| jd\$1source\$1uri | \$1source\$1uri | Default | String |
# IAM role for Microsoft SQL Server connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Microsoft Yammer to Amazon Q Business
Microsoft Yammer
**Note**
Microsoft Yammer connector remains fully supported for existing customers through May 31, 2026. While this connector is no longer available for new users, current users can continue to use it without interruption. We are continuously evolving our connector portfolio to offer more scalable and customizable solutions. For future integrations, we recommend exploring the [Amazon Q Business Custom Connector Framework](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-connector.html), designed to support a broader range of enterprise use cases with enhanced flexibility.
Microsoft Yammer is an enterprise collaboration tool for messaging, meetings, and file sharing. You can connect Microsoft Yammer instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# Known limitations for the Microsoft Yammer connector
](yammer-limitations.md)
+ [
# Microsoft Yammer connector overview
](yammer-overview.md)
+ [
# Prerequisites for connecting Amazon Q to Microsoft Yammer
](yammer-prereqs.md)
+ [
# Connecting Amazon Q Business to Microsoft Yammer using the console
](yammer-console.md)
+ [
# Connecting Amazon Q Business to Microsoft Yammer using APIs
](yammer-api.md)
+ [
# How Amazon Q Business connector crawls Microsoft Yammer ACLs
](yammer-user-management.md)
+ [
# Microsoft Yammer data source connector field mappings
](yammer-field-mappings.md)
+ [
# IAM role for Microsoft Yammer connector
](yammer-iam-role.md)
+ [
# Understand error codes in the Microsoft Yammer connector
](yammer-error-codes.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Microsoft Yammer connector
Known limitations
The Microsoft Yammer connector has the following known limitations:
+ Due to API limitations, an incremental sync will not update deleted **Messages**, **Attachments**, **Communities** and **Users**. To update deleted entities, you must run a full sync.
# Microsoft Yammer connector overview
Overview
The following table gives an overview of the Microsoft Yammer connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/yammer-overview.html)
# Prerequisites for connecting Amazon Q to Microsoft Yammer
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Microsoft Yammer, make sure you have:**
+ Created a Microsoft Yammer administrative account with verified admin user permissions.
+ Configured an OAuth 2.0 credential token containing a client ID and client secret.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Microsoft Yammer authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Microsoft Yammer using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Microsoft Yammer using the AWS Management Console.
**Connecting Amazon Q to Microsoft Yammer**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Microsoft Yammer** data source to your Amazon Q application.
1. Then, on the **Microsoft Yammer** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. **Authentication** – Choose between **New** and **Existing**.
1. If you choose **Existing**, select an existing secret for **Select secret**.
If you choose **New**, enter the following information in the **New AWS Secrets Manager secret** section:
+ **Secret name** – A name for your secret.
+ **Username** – The username for your Microsoft Yammer Active Directory account.
+ **Password** – The password for your Microsoft Yammer Active Directory account.
+ **Client ID** – The OAuth client ID credential values you copied from your Microsoft Yammer account.
+ **Client secret** – The client secret from your Microsoft Yammer account.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **Identity crawler** – Amazon Q crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/yammer-connector.html#yammer-iam).
1. For **Sync scope**, provide the following information:
+ **sinceDate** – Select the date in your data source content from when Amazon Q should begin to crawl your data.
+ **Select content to sync** – Choose between **All**, **Public messages**, **Attachments**, and **Inbox private messages**.
1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. For **Additional configuration – *optional***, provide the following information:
+ **Community names** – Enter the community names you wish to include in your application.
+ **Regex patterns** – Add regular expression patterns to include or exclude certain file types. You can add up to 100 patterns.
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Microsoft Yammer using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
## Yammer JSON schema
The following is the Yammer JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
}
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"community": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
},
"user": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
},
"message": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"type": "boolean"
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"inclusionPatterns": {
"type": "array"
},
"exclusionPatterns": {
"type": "array"
},
"sinceDate": {
"type": "string",
"pattern": "^(19|2[0-9])[0-9]{2}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T(0[0-9]|1[0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])((\\+|-)(0[0-9]|1[0-9]|2[0-3]):([0-5][0-9]))?$"
},
"communityNameFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"isCrawlMessage": {
"type": "boolean"
},
"isCrawlAttachment": {
"type": "boolean"
},
"isCrawlPrivateMessage": {
"type": "boolean"
}
},
"required": [
"sinceDate"
]
},
"type": {
"type": "string",
"pattern": "YAMMER"
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"useChangeLog": {
"type": "string",
"enum": [
"true",
"false"
]
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL",
"CHANGE_LOG"
]
},
"enableIdentityCrawler": {
"type": "boolean"
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties",
"type",
"secretArn",
"syncMode"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the data source. |
| repositoryEndpointMetadata | The endpoint information for the data source. This data source doesn't specify an endpoint in repositoryEndpointMetadata. Rather, the connection information is included in an AWS Secrets Manager secret that you provide the secretArn. |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/yammer-api.html) | A list of objects that map attributes or field names of Microsoft Yammer objects to Amazon Q index field names. |
| secretARN | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Microsoft Yammer data source. This includes your client ID and client secret. |
| additionalProperties | Additional configuration options for your content in your data source |
| isCrawlAcl | Specify true to crawl access control information from documents. Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. |
| maxFileSizeInMegaBytes | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. |
| fieldForUserId | Specify field to use for UserId for ACL crawling. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/yammer-api.html) | Input TRUE to index |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/yammer-api.html) | Use to specify the time from when Amazon Q should crawl your Microsoft Yammer content |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/yammer-api.html) | Use to specify community names to index. |
| inclusionPatterns | A list of regular expression patterns to include specific files in your Yammer data source. Files that match the patterns are included in the index. File that don't match the patterns are excluded from the index. Files that match the patterns are included in the index. Files that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence and the file isn't included in the index. |
| exclusionPatterns | A list of regular expression patterns to exclude specific files in your Yammer data source. Files that match the patterns are excluded from the files in your data source. Files that match the patterns are excluded from the index. Files that don't match the patterns are included in the index. If a file matches both an exclusion and inclusion pattern, the exclusion pattern takes precedence and the file isn't included in the index. |
| type | Specify YAMMER as your data source type |
| useChangeLog | true to use the Yammer change log to determine which documents require adding, updating, or deleting in the index. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/yammer-api.html) |
| enableIdentityCrawler | true to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to certain documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). |
# How Amazon Q Business connector crawls Microsoft Yammer ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an Microsoft Yammer data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your Microsoft Yammer instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
The group and user IDs are mapped as follows:
+ `_email_id` – Your Microsoft email ID is an identifier that's necessary to configure each connector instance. Your email ID can be found in the properties section of your Microsoft account dashboard.
+ `_group_id` – Group IDs exist in Microsoft Yammer Instances where there are set access permissions. They're mapped from the names of the groups in Microsoft Yammer.
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Microsoft Yammer data source connector field mappings
Field mappings
To help you structure data for retrieval and chat filtering, Amazon Q Business crawls data source document attributes or metadata and maps them to fields in your Amazon Q index.
Amazon Q has reserved fields that it uses when querying your application. When possible, Amazon Q automatically maps these built-in fields to attributes in your data source. If a built-in field doesn't have a default mapping, or if you want to map additional index fields, use the custom field mappings to specify how a data source attribute maps to your Amazon Q application. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Yammer connector supports the following entities and the associated reserved and custom attributes.
**Note**
You can map any Yammer field to the document title or document body Amazon Q reserved/default index fields.
**Topics**
+ [
## Message
](#yammer-field-mappings-message)
+ [
## Attachment
](#yammer-field-mappings-attachment)
+ [
## User
](#yammer-field-mappings-user)
+ [
## Community
](#yammer-field-mappings-community)
## Message
Amazon Q supports crawling [Microsoft Yammer Messages](https://learn.microsoft.com/en-us/rest/api/yammer/messagesjson) and offers the following message field mappings.
| Microsoft Yammer field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| id | ymr\$1id | Custom | String |
| message\$1type | ymr\$1message\$1type | Custom | String |
| api\$1url | ymr\$1api\$1url | Custom | String |
| group\$1id | ymr\$1group\$1id | Custom | String |
| group\$1name | ymr\$1group\$1name | Custom | String |
| in\$1private\$1conversation | ymr\$1in\$1private\$1conversation | Custom | String |
| in\$1private\$1group | ymr\$1in\$1private\$1group | Custom | String |
| sender\$1email | ymr\$1sender\$1email | Custom | String |
| sender\$1id | ymr\$1sender\$1id | Custom | String |
| sender\$1name | ymr\$1sender\$1name | Custom | String |
| created\$1at | \$1created\$1at | Default | Date |
| web\$1url | \$1source\$1uri | Default | String |
## Attachment
| Microsoft Yammer field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| id | ymr\$1attachment\$1id | Custom | String |
| name | ymr\$1attachment\$1name | Custom | String |
| size | ymr\$1attachment\$1size | Custom | String |
| url | ymr\$1attachment\$1url | Custom | String |
| file\$1type | ymr\$1attachment\$1type | Custom | String |
| created\$1at | \$1created\$1at | Default | Date |
| privacy | ymr\$1attachment\$1privacy | Custom | String |
| group\$1name | ymr\$1attachment\$1group\$1name | Custom | String |
| sender\$1email | ymr\$1attachment\$1sender\$1email | Custom | String |
| web\$1url | \$1source\$1uri | Default | String |
## User
| Microsoft Yammer field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| id | ymr\$1user\$1id | Custom | String |
| user\$1type | ymr\$1user\$1type | Custom | String |
| state | ymr\$1user\$1state | Custom | String |
| full\$1name | ymr\$1user\$1full\$1name | Custom | String |
| activated\$1at | \$1created\$1at | Default | Date |
| first\$1name | ymr\$1user\$1first\$1name | Custom | String |
| last\$1name | ymr\$1user\$1last\$1name | Custom | String |
| network\$1name | ymr\$1user\$1network\$1name | Custom | String |
| network\$1domains | ymr\$1user\$1network\$1domains | Custom | String |
| url | ymr\$1user\$1url | Custom | String |
| name | ymr\$1user\$1name | Custom | String |
| birth\$1date | ymr\$1user\$1birth\$1date | Custom | Date |
| admin | ymr\$1user\$1admin | Custom | String |
| verified\$1admin | ymr\$1user\$1verified\$1admin | Custom | String |
| contact | ymr\$1user\$1contact | Custom | String |
| email | ymr\$1user\$1email | Custom | String |
| web\$1url | \$1source\$1uri | Default | String |
## Community
| Microsoft Yammer field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| id | ymr\$1community\$1id | Custom | String |
| name | ymr\$1community\$1name | Custom | String |
| email | ymr\$1community\$1email | Custom | String |
| full\$1name | ymr\$1community\$1full\$1name | Custom | String |
| description | ymr\$1community\$1description | Custom | String |
| privacy | ymr\$1community\$1privacy | Custom | String |
| url | ymr\$1community\$1url | Custom | String |
| created\$1at | \$1created\$1at | Default | Date |
| state | ymr\$1community\$1state | Custom | String |
| web\$1url | \$1source\$1uri | Default | String |
# IAM role for Microsoft Yammer connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Understand error codes in the Microsoft Yammer connector
Error Codes
The following table provides information about error codes you may see for the Microsoft Yammer connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| YMR-5001 | Authentication error. | Provide a valid client id, client secret, username, password. |
| YMR-5002 | Error validating credentials due to invalid username or password. | Provide a valid username and password. |
| YMR-5003 | Error validating credentials due to invalid client id or client secret. | Provide valid client id and client secret. |
| YMR-5004 | Access token is empty or null . | Provide non-empty or non-null access token . |
| YMR-5100 | Null/empty client id. | Provide client id. |
| YMR-5101 | Null/empty client secret. | Provide client secret. |
| YMR-5102 | Null/empty username. | Provide username. |
| YMR-5103 | Null/empty password. | Provide password . |
| YMR-5104 | Null/empty since date. | Provide sinceDate . |
| YMR-5105 | invalid sinceDate format. | since date format should be like YYYY-MM-DDTHH:mm:ss\$100:00. |
| YMR-5106 | Empty/null Repository configurations. | Provide Repository configurations. |
| YMR-5107 | Empty/null message entity in repository configuration. | Provide message entity in repository configuration. |
| YMR-5108 | Empty/null Attachment entity in repository configuration. | Provide attachment entity in repository configuration. |
| YMR-5109 | Empty/null message entity field mapping. | Provide message entity field mapping. |
| YMR-5110 | Empty/null attachment entity field mapping. | Provide attachment entity field mapping. |
| YMR-5111 | Empty/null indexFieldName, indexFieldType or dataSourceFieldName in message entity. | Provide value for indexFieldName, indexFieldType and dataSourceFieldName in message entity. |
| YMR-5112 | Empty/null indexFieldName, indexFieldType or dataSourceFieldName in attachment entity. | Provide value for indexFieldName, indexFieldType and dataSourceFieldName in message entity. |
| YMR-5113 | Invalid patterns in the regex. | Provide valid regex patterns. |
| YMR-5114 | Since date should be less than current date. | Provide since date less than current date. |
| YMR-5115 | Only String, Date and Long formats are supported for field mappings. | Provide String, Date and Long formats for field mappings. |
| YMR-5116 | Null/empty Network Domain. | Provide Network Domain. |
| YMR-5117 | Got error while building groups. | Refer to logs for more information. |
| YMR-5118 | Configuration found null during change access token. | Please provide valid configurations. |
| YMR-5119 | Unable to connect to Yammer account. | Refer to logs for more details. |
| YMR-5120 | An error occurred during the test connection. | Refer to logs for more details. |
| YMR-5500 | Bad zip entry. | Provide a valid zip file. |
| YMR-5501 | Invalid URI. | Provide valid URI. |
| YMR-5502 | ContinuableInternalServerError. | Try again later. |
# Connecting MySQL to Amazon Q Business
MySQL
**Note**
MySQL connector remains fully supported for existing customers through May 31, 2026. While this connector is no longer available for new users, current users can continue to use it without interruption. We are continuously evolving our connector portfolio to offer more scalable and customizable solutions. For future integrations, we recommend exploring the [Amazon Q Business Custom Connector Framework](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-connector.html), designed to support a broader range of enterprise use cases with enhanced flexibility.
MySQL is an open source relational database management system. You can connect your MySQL instance to Amazon Q Business—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
The Amazon Q MySQL data source connector supports MySQL 8.0. 21.
**Important**
As a best practice, provide Amazon Q with read-only database credentials. Also, avoid adding tables with sensitive data or personal identifiable information (PII).
**Topics**
+ [
# Known limitations for the MySQL connector
](my-sql-limitations.md)
+ [
# MySQL connector overview
](my-sql-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to MySQL
](my-sql-prereqs.md)
+ [
# Connecting Amazon Q Business to MySQL using the console
](my-sql-console.md)
+ [
# Connecting Amazon Q Business to MySQL using APIs
](my-sql-api.md)
+ [
# How Amazon Q Business connector crawls MySQL ACLs
](my-sql-user-management.md)
+ [
# MySQL data source connector field mappings
](my-sql-field-mappings.md)
+ [
# IAM role for MySQL connector
](my-sql-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the MySQL connector
Known limitations
+ Deleted database rows will not be tracked in when Amazon Q checks for updated content.
+ The size of field names and values in a row of your database can't exceed 400KB.
+ Column names should only contain alphanumeric characters and not spaces.
+ If you have a large amount of data in your database data source, and do not want Amazon Q to index all your database content after the first sync, you can choose to sync only new, modified, or deleted documents.
# MySQL connector overview
Overview
The following table gives an overview of the Amazon Q Business MySQL connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/my-sql-overview.html)
# Prerequisites for connecting Amazon Q Business to MySQL
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In MySQL, make sure you have:**
+ Noted your database username and password.
**Important**
As a best practice, provide Amazon Q with read-only database credentials.
+ Copied your database host URL, port, and instance.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your MySQL authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to MySQL using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to MySQL using the AWS Management Console.
**Connecting Amazon Q to MySQL**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **MySQL** data source to your Amazon Q application.
1. Then, on the **MySQL** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
1. **Host** – Enter the database host name.
1. **Port** – Enter the database port.
1. **Instance** – Enter the database instance.
1. **Enable SSL certificate location** – Choose to enter the Amazon S3 path to your SSL certificate file.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. In **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. For **Database username**, and **Password** – Enter the authentication credential values you copied from your database.
1. Choose **Save**.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/my-sql-connector.html#my-sql-iam).
1. In **Sync scope**, enter the following information:
+ **SQL query** – Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query.
+ **Primary key column** – Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data.
+ **Title column** – Provide the name of the column in your database table that you want to designate as the column with document titles.
+ **Body column** – Provide the name of the column in your database table that you want to designate as the column with document body text.
Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Additional configuration – *optional*** – Configure the following settings:
+ **Change-detecting columns** – Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns.
+ **Users' IDs column** – Enter the name of the column which contains User IDs to be allowed access to content.
+ **Groups column** – Enter the name of the column that contains groups to be allowed access to content.
+ **Source URLs column** – Enter the name of the column which contains Source URLs to be indexed.
+ **Time stamps column** – Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content.
+ **Time zones column** – Enter the name of the column which contains time zones for the content to be crawled.
+ **Time stamps format** – Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content.
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to MySQL using APIs
Using the API
You use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application.
Then, you use the `configuration` parameter to provide a JSON schema with all other configuration information specific to your data source connector.
## MySQL JSON schema
The following is the MySQL JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"dbType": {
"type": "string",
"enum": [
"mysql",
"db2",
"postgresql",
"oracle",
"sqlserver"
]
},
"dbHost": {
"type": "string"
},
"dbPort": {
"type": "string"
},
"dbInstance": {
"type": "string"
}
},
"required": [
"dbType",
"dbHost",
"dbPort",
"dbInstance"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"document": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string"
},
"dataSourceFieldName": {
"type": "string"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
}
},
"required": [
]
},
"additionalProperties": {
"type": "object",
"properties": {
"primaryKey": {
"type": "string"
},
"titleColumn": {
"type": "string"
},
"bodyColumn": {
"type": "string"
},
"sqlQuery": {
"type": "string",
"not": {
"pattern": ";+"
}
},
"timestampColumn": {
"type": "string"
},
"timestampFormat": {
"type": "string"
},
"timezone": {
"type": "string"
},
"changeDetectingColumns": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedUsersColumn": {
"type": "string"
},
"allowedGroupsColumn": {
"type": "string"
},
"sourceURIColumn": {
"type": "string"
},
"serverlessAurora": {
"type": "string",
"enum": ["true", "false"]
}
},
"required": ["primaryKey", "titleColumn", "bodyColumn", "sqlQuery"]
},
"type" : {
"type" : "string",
"pattern": "JDBC"
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL",
"CHANGE_LOG"
]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | Required configuration information for connecting your data source.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/my-sql-api.html) |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. Specify the type of data source and the secret ARN. |
| document | A list of objects that map the attributes or field names of your database content to Amazon Q index field names. For more information, see [Fiel](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings). |
| additionalProperties | Additional configuration options for your content in your data source. Use to include or exclude specific content in your database data source. |
| primaryKey | Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data. |
| titleColumn | Provide the name of the column in your database table that you want to designate as the column with document titles. |
| bodyColumn | Provide the name of the column in your database table that you want to designate as the column with document body text. Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias. |
| sqlQuery | Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query. |
| timestampColumn | Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content. |
| timestampFormat | Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content. |
| timezone | Enter the name of the column which contains time zones for the content to be crawled. |
| changeDetectingColumns | Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns |
| allowedUsersColumns | Enter the name of the column which contains User IDs to be allowed access to content. |
| allowedGroupsColumn | Enter the name of the column which contains User IDs to be allowed access to content. |
| sourceURIColumn | Enter the name of the column which contains Source URLs to be indexed. |
| isSslEnabled | true to add a path to an SSL certificate file stored in an Amazon S3 bucket. |
| type | The type of data source. Specify JDBC as your data source type. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/my-sql-api.html) |
| secretArn | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains username and password required to connect to your database. The secret must contain a JSON structure with the following keys: {
"username": "database username",
"password": "password"
} |
| version | The version of the template that is currently supported. |
# How Amazon Q Business connector crawls MySQL ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect a database data source to Amazon Q, Amazon Q crawls user and group information from a column in the source table. You specify this column in the console or using the `configuration` parameter as part of the `CreateDataSource` operation.
If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
A database data source has the following limitations:
+ You can only specify an allow list for a database data source. You can't specify a deny list.
+ You can only specify groups. You can't specify individual users for the allow list.
+ The database column should be a string containing a semicolon delimited list of groups.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# MySQL data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q PostgreSQL connector supports the following field mappings:
**Topics**
+ [
## Document
](#my-sql-field-mappings-document)
## Document
| JDBC field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| jd\$1document\$1id | jd\$1document\$1id | Custom | String |
| jd\$1document\$1title | jd\$1document\$1title | Custom | String |
| jd\$1source\$1uri | \$1source\$1uri | Default | String |
# IAM role for MySQL connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Oracle Database to Amazon Q Business
Oracle Database
**Note**
Oracle Database connector remains fully supported for existing customers through May 31, 2026. While this connector is no longer available for new users, current users can continue to use it without interruption. We are continuously evolving our connector portfolio to offer more scalable and customizable solutions. For future integrations, we recommend exploring the [Amazon Q Business Custom Connector Framework](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-connector.html), designed to support a broader range of enterprise use cases with enhanced flexibility.
Oracle Database is a database management system. You can connect your Oracle Database instance to Amazon Q Business—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
The Amazon Q Oracle Database data source connector supports Oracle Database 18c, 19c, and 21c.
**Important**
As a best practice, provide Amazon Q with read-only database credentials. Also, avoid adding tables with sensitive data or personal identifiable information (PII).
**Topics**
+ [
# Known limitations for the Oracle Database connector
](oracle-database-limitations.md)
+ [
# Oracle Database connector overview
](oracle-database-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Oracle Database
](oracle-database-prereqs.md)
+ [
# Connecting Amazon Q Business to Oracle Database using the console
](oracle-database-console.md)
+ [
# Connecting Amazon Q Business to Oracle Database using APIs
](oracle-database-api.md)
+ [
# How Amazon Q Business connector crawls Oracle Database ACLs
](oracle-database-user-management.md)
+ [
# Amazon Q Business data source connector field mappings
](oracle-database-field-mappings.md)
+ [
# IAM role for Oracle Database connector
](oracle-database-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Oracle Database connector
Known limitations
+ Deleted database rows will not be tracked in when Amazon Q checks for updated content.
+ The size of field names and values in a row of your database can't exceed 400KB.
+ Column names should only contain alphanumeric characters and not spaces.
+ If you have a large amount of data in your database data source, and do not want Amazon Q to index all your database content after the first sync, you can choose to sync only new, modified, or deleted documents.
# Oracle Database connector overview
Overview
The following table gives an overview of the Amazon Q Oracle Database connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/oracle-database-overview.html)
# Prerequisites for connecting Amazon Q Business to Oracle Database
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Oracle Database, make sure you have:**
+ Noted your database username and password.
**Important**
As a best practice, provide Amazon Q with read-only database credentials.
+ Copied your database host URL, port, and instance.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Oracle Database authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Oracle Database using the console
Using the console
The following procedure outlines how to connect Amazon Q to Oracle Database using the AWS Management Console.
**Connecting Amazon Q to Oracle Database**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Oracle Database** data source to your Amazon Q application.
1. Then, on the **Oracle Database** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
1. **Host** – Enter the database host name.
1. **Port** – Enter the database port.
1. **Instance** – Enter the database instance.
1. **Enable SSL certificate location** – Choose to enter the Amazon S3 path to your SSL certificate file.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. In **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. For **Database username**, and **Password** – Enter the authentication credential values you copied from your database.
1. Choose **Save**.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/oracle-database-connector.html#oracle-database-iam).
1. In **Sync scope**, enter the following information:
+ **SQL query** – Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query.
+ **Primary key column** – Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data.
+ **Title column** – Provide the name of the column in your database table that you want to designate as the column with document titles.
+ **Body column** – Provide the name of the column in your database table that you want to designate as the column with document body text.
Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Additional configuration – *optional*** – Configure the following settings:
+ **Change-detecting columns** – Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns.
+ **Users' IDs column** – Enter the name of the column which contains User IDs to be allowed access to content.
+ **Groups column** – Enter the name of the column that contains groups to be allowed access to content.
+ **Source URLs column** – Enter the name of the column which contains Source URLs to be indexed.
+ **Time stamps column** – Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content.
+ **Time zones column** – Enter the name of the column which contains time zones for the content to be crawled.
+ **Time stamps format** – Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content.
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Oracle Database using APIs
Using the API
You use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application.
Then, you use the `configuration` parameter to provide a JSON schema with all other configuration information specific to your data source connector.
## Oracle Database JSON schema
The following is the Oracle Database JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"dbType": {
"type": "string",
"enum": [
"mysql",
"db2",
"postgresql",
"oracle",
"sqlserver"
]
},
"dbHost": {
"type": "string"
},
"dbPort": {
"type": "string"
},
"dbInstance": {
"type": "string"
}
},
"required": [
"dbType",
"dbHost",
"dbPort",
"dbInstance"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"document": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string"
},
"dataSourceFieldName": {
"type": "string"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
}
},
"required": [
]
},
"additionalProperties": {
"type": "object",
"properties": {
"primaryKey": {
"type": "string"
},
"titleColumn": {
"type": "string"
},
"bodyColumn": {
"type": "string"
},
"sqlQuery": {
"type": "string",
"not": {
"pattern": ";+"
}
},
"timestampColumn": {
"type": "string"
},
"timestampFormat": {
"type": "string"
},
"timezone": {
"type": "string"
},
"changeDetectingColumns": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedUsersColumn": {
"type": "string"
},
"allowedGroupsColumn": {
"type": "string"
},
"sourceURIColumn": {
"type": "string"
},
"serverlessAurora": {
"type": "string",
"enum": ["true", "false"]
}
},
"required": ["primaryKey", "titleColumn", "bodyColumn", "sqlQuery"]
},
"type" : {
"type" : "string",
"pattern": "JDBC"
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL",
"CHANGE_LOG"
]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | Required configuration information for connecting your data source.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/oracle-database-api.html) |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. Specify the type of data source and the secret ARN. |
| document | A list of objects that map the attributes or field names of your database content to Amazon Q index field names. For more information, see [Fiel](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings). |
| additionalProperties | Additional configuration options for your content in your data source. Use to include or exclude specific content in your database data source. |
| primaryKey | Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data. |
| titleColumn | Provide the name of the column in your database table that you want to designate as the column with document titles. |
| bodyColumn | Provide the name of the column in your database table that you want to designate as the column with document body text. Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias. |
| sqlQuery | Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query. |
| timestampColumn | Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content. |
| timestampFormat | Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content. |
| timezone | Enter the name of the column which contains time zones for the content to be crawled. |
| changeDetectingColumns | Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns |
| allowedUsersColumns | Enter the name of the column which contains User IDs to be allowed access to content. |
| allowedGroupsColumn | Enter the name of the column which contains User IDs to be allowed access to content. |
| sourceURIColumn | Enter the name of the column which contains Source URLs to be indexed. |
| isSslEnabled | true to add a path to an SSL certificate file stored in an Amazon S3 bucket. |
| type | The type of data source. Specify JDBC as your data source type. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/oracle-database-api.html) |
| secretArn | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains username and password required to connect to your database. The secret must contain a JSON structure with the following keys: {
"username": "database username",
"password": "password"
} |
| version | The version of the template that is currently supported. |
# How Amazon Q Business connector crawls Oracle Database ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect a database data source to Amazon Q, Amazon Q crawls user and group information from a column in the source table. You specify this column in the console or using the `configuration` parameter as part of the `CreateDataSource` operation.
If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
A database data source has the following limitations:
+ You can only specify an allow list for a database data source. You can't specify a deny list.
+ You can only specify groups. You can't specify individual users for the allow list.
+ The database column should be a string containing a semicolon delimited list of groups.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Amazon Q Business data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q PostgreSQL connector supports the following field mappings:
**Topics**
+ [
## Document
](#oracle-database-field-mappings-document)
## Document
| JDBC field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| jd\$1document\$1id | jd\$1document\$1id | Custom | String |
| jd\$1document\$1title | jd\$1document\$1title | Custom | String |
| jd\$1source\$1uri | \$1source\$1uri | Default | String |
# IAM role for Oracle Database connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting PostgreSQL to Amazon Q Business
PostgreSQL
**Note**
PostgreSQL connector remains fully supported for existing customers through May 31, 2026. While this connector is no longer available for new users, current users can continue to use it without interruption. We are continuously evolving our connector portfolio to offer more scalable and customizable solutions. For future integrations, we recommend exploring the [Amazon Q Business Custom Connector Framework](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-connector.html), designed to support a broader range of enterprise use cases with enhanced flexibility.
PostgreSQL is an open source database management system. You can connect your PostgreSQL instance to Amazon Q Business—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
The Amazon Q PostgreSQL data source connector supports PostgreSQL 9.6.
**Important**
As a best practice, provide Amazon Q with read-only database credentials. Also, avoid adding tables with sensitive data or personal identifiable information (PII).
**Topics**
+ [
# Known limitations for the PostgreSQL connector
](postgresql-limitations.md)
+ [
# PostgreSQL connector overview
](postgresql-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to PostgreSQL
](postgresql-prereqs.md)
+ [
# Connecting Amazon Q Business to PostgreSQL using the console
](postgresql-console.md)
+ [
# Connecting Amazon Q Business to PostgreSQL using APIs
](postgresql-api.md)
+ [
# How Amazon Q Business connector crawls PostgreSQL ACLs
](postgresql-user-management.md)
+ [
# PostgreSQL data source connector field mappings
](postgresql-field-mappings.md)
+ [
# IAM role for PostgreSQL connector
](postgresql-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the PostgreSQL connector
Known limitations
+ Deleted database rows will not be tracked in when Amazon Q checks for updated content.
+ The size of field names and values in a row of your database can't exceed 400KB.
+ Column names should only contain alphanumeric characters and not spaces.
+ If you have a large amount of data in your database data source, and do not want Amazon Q to index all your database content after the first sync, you can choose to sync only new, modified, or deleted documents.
# PostgreSQL connector overview
Overview
The following table gives an overview of the Amazon Q Business PostgreSQL connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/postgresql-overview.html)
# Prerequisites for connecting Amazon Q Business to PostgreSQL
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In PostgreSQL, make sure you have:**
+ Noted your database username and password.
**Important**
As a best practice, provide Amazon Q with read-only database credentials.
+ Copied your database host URL, port, and instance.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your PostgreSQL authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to PostgreSQL using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to PostgreSQL using the AWS Management Console.
**Connecting Amazon Q to PostgreSQL**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **PostgreSQL** data source to your Amazon Q application.
1. Then, on the **PostgreSQL** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
1. **Host** – Enter the database host URL.
1. **Port** – Enter the database port, for example, `5432`.
1. **Instance** – Enter the database instance, for example `postgres`.
1. **Enable SSL certificate location** – Choose to enter the Amazon S3 path to your SSL certificate file.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. In **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. For **Database username**, and **Password** – Enter the authentication credential values you copied from your database.
1. Choose **Save**.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/postgresql-connector.html#postgresql-iam).
1. In **Sync scope**, enter the following information:
+ **SQL query** – Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query.
+ **Primary key column** – Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data.
+ **Title column** – Provide the name of the column in your database table that you want to designate as the column with document titles.
+ **Body column** – Provide the name of the column in your database table that you want to designate as the column with document body text.
Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Additional configuration – *optional*** – Configure the following settings:
+ **Change-detecting columns** – Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns.
+ **Users' IDs column** – Enter the name of the column which contains User IDs to be allowed access to content.
+ **Groups column** – Enter the name of the column that contains groups to be allowed access to content.
+ **Source URLs column** – Enter the name of the column which contains Source URLs to be indexed.
+ **Time stamps column** – Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content.
+ **Time zones column** – Enter the name of the column which contains time zones for the content to be crawled.
+ **Time stamps format** – Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content.
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to PostgreSQL using APIs
Using the API
You use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application.
Then, you use the `configuration` parameter to provide a JSON schema with all other configuration information specific to your data source connector.
## PostgreSQL JSON schema
The following is the PostgreSQL JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"dbType": {
"type": "string",
"enum": [
"mysql",
"db2",
"postgresql",
"oracle",
"sqlserver"
]
},
"dbHost": {
"type": "string"
},
"dbPort": {
"type": "string"
},
"dbInstance": {
"type": "string"
}
},
"required": [
"dbType",
"dbHost",
"dbPort",
"dbInstance"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"document": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string"
},
"dataSourceFieldName": {
"type": "string"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
}
},
"required": [
]
},
"additionalProperties": {
"type": "object",
"properties": {
"primaryKey": {
"type": "string"
},
"titleColumn": {
"type": "string"
},
"bodyColumn": {
"type": "string"
},
"sqlQuery": {
"type": "string",
"not": {
"pattern": ";+"
}
},
"timestampColumn": {
"type": "string"
},
"timestampFormat": {
"type": "string"
},
"timezone": {
"type": "string"
},
"changeDetectingColumns": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedUsersColumn": {
"type": "string"
},
"allowedGroupsColumn": {
"type": "string"
},
"sourceURIColumn": {
"type": "string"
},
"serverlessAurora": {
"type": "string",
"enum": ["true", "false"]
}
},
"required": ["primaryKey", "titleColumn", "bodyColumn", "sqlQuery"]
},
"type" : {
"type" : "string",
"pattern": "JDBC"
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL",
"CHANGE_LOG"
]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | Required configuration information for connecting your data source.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/postgresql-api.html) |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. Specify the type of data source and the secret ARN. |
| document | A list of objects that map the attributes or field names of your database content to Amazon Q index field names. For more information, see [Fiel](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings). |
| additionalProperties | Additional configuration options for your content in your data source. Use to include or exclude specific content in your database data source. |
| primaryKey | Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data. |
| titleColumn | Provide the name of the column in your database table that you want to designate as the column with document titles. |
| bodyColumn | Provide the name of the column in your database table that you want to designate as the column with document body text. Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias. |
| sqlQuery | Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query. |
| timestampColumn | Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content. |
| timestampFormat | Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content. |
| timezone | Enter the name of the column which contains time zones for the content to be crawled. |
| changeDetectingColumns | Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns |
| allowedUsersColumns | Enter the name of the column which contains User IDs to be allowed access to content. |
| allowedGroupsColumn | Enter the name of the column which contains User IDs to be allowed access to content. |
| sourceURIColumn | Enter the name of the column which contains Source URLs to be indexed. |
| isSslEnabled | true to add a path to an SSL certificate file stored in an Amazon S3 bucket. |
| type | The type of data source. Specify JDBC as your data source type. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/postgresql-api.html) |
| secretArn | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains username and password required to connect to your database. The secret must contain a JSON structure with the following keys: {
"username": "database username",
"password": "password"
} |
| version | The version of the template that is currently supported. |
# How Amazon Q Business connector crawls PostgreSQL ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect a database data source to Amazon Q, Amazon Q crawls user and group information from a column in the source table. You specify this column in the console or using the `configuration` parameter as part of the `CreateDataSource` operation.
If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
A database data source has the following limitations:
+ You can only specify an allow list for a database data source. You can't specify a deny list.
+ You can only specify groups. You can't specify individual users for the allow list.
+ The database column should be a string containing a semicolon delimited list of groups.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# PostgreSQL data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q PostgreSQL connector supports the following field mappings:
**Topics**
+ [
## Document
](#postgresql-field-mappings-document)
## Document
| JDBC field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| jd\$1document\$1id | jd\$1document\$1id | Custom | String |
| jd\$1document\$1title | jd\$1document\$1title | Custom | String |
| jd\$1source\$1uri | \$1source\$1uri | Default | String |
# IAM role for PostgreSQL connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Quip to Amazon Q Business
Quip
**Note**
Quip connector remains fully supported for existing customers through May 31, 2026. While this connector is no longer available for new users, current users can continue to use it without interruption. We are continuously evolving our connector portfolio to offer more scalable and customizable solutions. For future integrations, we recommend exploring the [Amazon Q Business Custom Connector Framework](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-connector.html), designed to support a broader range of enterprise use cases with enhanced flexibility.
Quip is a collaborative productivity software that offers real time document-authoring capabilities. You can connect your Quip instance to Amazon Q Business—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# Known limitations for the Amazon Q Business Quip connector
](quip-limitations.md)
+ [
# Quip connector overview
](quip-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Quip
](quip-prereqs.md)
+ [
# Retrieving Quip credentials
](quip-credentials.md)
+ [
# Connecting Amazon Q Business to Quip using the console
](quip-console.md)
+ [
# Connecting Amazon Q Business to Quip using APIs
](quip-api.md)
+ [
# How Amazon Q Business connector crawls Quip ACLs
](quip-user-management.md)
+ [
# Quip data source connector field mappings
](quip-field-mappings.md)
+ [
# IAM role for Amazon Q Business Quip connector
](quip-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Amazon Q Business Quip connector
Known limitations
The Quip connector has the following known limitations:
+ Only **Full sync** is supported by default. For **New, modified, or deleted content sync**, Admin API access is required and Admin API has to be enabled on the Quip website .
+ Only data in shared folders will be crawled by the Amazon Q Quip connector. Private folders, other than the private folders belonging to the Private Access Token user, will not be crawled.
+ Quip doesn't store file types and file paths. Amazon Q Quip connector can't support inclusion and exclusion filters on these.
# Quip connector overview
Overview
The following table gives an overview of the Quip connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quip-overview.html)
# Prerequisites for connecting Amazon Q Business to Quip
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Quip, make sure you have:**
+ A Quip account with administrative permissions.
+ Created Quip authentication credentials that include a personal access token. See [Quip documentation on authentication](https://quip.com/dev/admin/documentation/current#section/Authentication) for more information.
+ Copied your Quip site domain. For example, *https://quip-company.quipdomain.com/browse* where *quipdomain* is the domain.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Quip authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Retrieving Quip credentials
Setting up Quip
Before you connect Quip to Amazon Q, you need to create and retrieve the Quip credentials you will use to connect Quip to Amazon Q.
The following procedure gives you an overview of how to configure Quip for connecting with Amazon Q by creating a API access token.
**Configuring Quip authentication for Amazon Q**
1. Log in to your Quip account using a web browser of your choice and sign into your Quip workspace.
**Note**
To configure Quip for Amazon Q, you must be an admin user in the Quip account.
1. From the browser URL, note your Quip domain name. You will need this both to connect to Amazon Q and also to generate an API access token.
![\[Screenshot of the Quip interface showing the account settings menu where users can access developer tools to generate an API token.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/quip-1.png)
1. In a text editor of your choice, copy and paste the following: `https://domain/dev/token`. Then, replace *domain* with the Quip domain you copied in the last step. Copy the URL.
1. Open a new browser window and paste the formatted URL you created in the last step. Quip will return an API access token in your browser window.
![\[Screenshot of the Quip developer token page showing the generated personal access token that needs to be copied for API authentication.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/quip-2.png)
You now have the Quip domain name and Quip API access token you need to connect to Amazon Q.
# Connecting Amazon Q Business to Quip using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Quip using the AWS Management Console.
**Connecting Amazon Q to Quip**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Quip** data source to your Amazon Q application.
1. Then, on the **Quip** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. **Source** – Enter your **Quip domain name**. You can find your domain name in the browser URL of your Quip. For example, *https://quip-company.quipdomain.com/browse*, the domain is "quipdomain".
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. **Quip token** – Enter the Quip personal access token you created in your Quip account.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quip-connector.html#quip-iam).
1. In **Sync scope**, enter the following information:
1. **Add Quip folder IDs to crawl** – Enter the Quip folder IDs you want to crawl. You can find your folder ID in the browser URL when you access your folder in Quip. For example, *https://quip-company.quipdomain.com/zlLuOVNSarTL/folder-name*, the folder ID is "zlLuOVNSarTL"..
**Note**
To crawl a root folder, including all sub-folders and documents inside it, input the root folder ID. To crawl specific sub-folders, add the specific sub-folder IDs.
1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB.
1. (Optional) **Additional configuration – *optional*** – Configure the following settings:
+ **Content types** – Choose between crawling **All content**, **File comments**, **Chat rooms** and **Attachments**.
+ **Regex patterns** – Add regex patterns to include or exclude file names, file types, or file paths. You can have a total of 100 patterns.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. For **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Quip using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
## Quip JSON schema
The following is the Quip JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"domain": {
"type": "string"
}
},
"required": [
"domain"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"thread": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"STRING_LIST",
"DATE"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
},
"message": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"STRING_LIST",
"DATE"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"STRING_LIST",
"DATE"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"type": "boolean"
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"folderIds": {
"type": "array",
"items": {
"type": "string"
}
},
"crawlFileComments": {
"type": "boolean"
},
"crawlChatRooms": {
"type": "boolean"
},
"crawlAttachments": {
"type": "boolean"
},
"inclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": []
},
"type": {
"type": "string",
"pattern": "QUIP"
},
"syncMode": {
"type": "string",
"enum": [
"FULL_CRAWL",
"FORCED_FULL_CRAWL"
]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | The endpoint information for the data source. |
| domain | Your Quip site domain. For example, https://quip-company.quipdomain.com/browse where quipdomain is the domain. |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quip-api.html) | A list of objects that map the attributes or field names of your Quip pages and assets to Amazon Q index field names. |
| additionalProperties | Additional configuration options for your content in your data source. |
| isCrawlAcl | Specify true to crawl access control information from documents. Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. |
| maxFileSizeInMegaBytes | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. |
| fieldForUserId | Specify field to use for UserId for ACL crawling. |
| folderIds | Specify folder IDs to crawl. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quip-api.html) | true to index. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quip-api.html) | A list of regular expression patterns to include specific content in your Quip data source. Content that matches the patterns are included in the index. Content that doesn't match the pattern are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quip-api.html) | A list of regular expression patterns to exclude specific content in your Quip data source. Content that matches the patterns are excluded from the index. Content that doesn't match the patterns are included in the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. |
| type | The type of data source. Specify QUIP as your data source type. |
| enableIdentityCrawler | Specify true to use the Amazon Q identity crawler to sync identity/principal information on users and groups with access to specific documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quip-api.html) |
| secretArn | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Quip. The secret must contain a JSON structure with the following keys: {
"accessToken": "token"
} |
| version | The version of this template that's currently supported. |
# How Amazon Q Business connector crawls Quip ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an Quip data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your Quip instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
The Quip user IDs are mapped as follows:
+ `_user_id`—User IDs exist in Quip on files where there are set access permissions. They are mapped from the user emails as the IDs in Quip.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Quip data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Quip connector supports the following entities and the associated reserved and custom attributes.
**Note**
You can map any Quip field to the document title or document body Amazon Q reserved/default index fields.
**Topics**
+ [
## Thread
](#quip-field-mappings-thread)
+ [
## Message
](#quip-field-mappings-message)
+ [
## Attachment
](#quip-field-mappings-attachment)
## Thread
Amazon Q supports crawling [Quip Threads](https://quip.com/dev/automation/documentation/current#tag/Threads) and offers the following thread field mappings.
| Quip field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| qp\$1authors | \$1authors | Default | String list |
| qp\$1category | \$1category | Default | String |
| qp\$1file\$1type | qp\$1file\$1type | Custom | String |
| qp\$1document\$1title | qp\$1document\$1title | Custom | String |
| qp\$1source\$1uri | \$1source\$1uri | Default | String |
| qp\$1created\$1at | \$1created\$1at | Default | Date |
| qp\$1updated\$1at | \$1last\$1updated\$1at | Default | Date |
## Message
Amazon Q supports crawling [Quip Messages](https://quip.com/dev/automation/documentation/current#tag/Messages) and offers the following message field mappings.
| Quip field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| qp\$1authors | \$1authors | Default | String list |
| qp\$1category | \$1category | Default | String |
| qp\$1source\$1uri | \$1source\$1uri | Default | String |
| qp\$1parent\$1file | qp\$1parent\$1file | Custom | String |
| qp\$1created\$1at | \$1created\$1at | Default | Date |
| qp\$1updated\$1at | \$1last\$1updated\$1at | Default | Date |
## Attachment
Amazon Q supports crawling Quip attachments and offers the following attachment field mappings.
| Quip field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| qp\$1authors | \$1authors | Default | String list |
| qp\$1category | \$1category | Default | String |
| qp\$1source\$1uri | \$1source\$1uri | Default | String |
| qp\$1file\$1type | qp\$1file\$1type | Custom | String |
| qp\$1parent\$1file | qp\$1parent\$1file | Custom | String |
| qp\$1blob\$1id | qp\$1blob\$1id | Custom | String |
| qp\$1created\$1at | \$1created\$1at | Default | Date |
| qp\$1updated\$1at | \$1last\$1updated\$1at | Default | Date |
# IAM role for Amazon Q Business Quip connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Amazon RDS (Microsoft SQL Server) to Amazon Q Business
Amazon RDS (Microsoft SQL Server)
**Note**
Amazon RDS (Microsoft SQL Server) connector remains fully supported for existing customers through May 31, 2026. While this connector is no longer available for new users, current users can continue to use it without interruption. We are continuously evolving our connector portfolio to offer more scalable and customizable solutions. For future integrations, we recommend exploring the [Amazon Q Business Custom Connector Framework](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-connector.html), designed to support a broader range of enterprise use cases with enhanced flexibility.
Amazon RDS (Microsoft SQL Server) is a relational database management system (RDBMS) built for the cloud. You can connect your Amazon RDS (Microsoft SQL Server) instance to Amazon Q Business – using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API – and create an Amazon Q web experience.
The Amazon Q Microsoft SQL Server data source connector supports MS SQL Server 2019.
**Important**
As a best practice, provide Amazon Q with read-only database credentials. Also, avoid adding tables with sensitive data or personal identifiable information (PII).
**Topics**
+ [
# Known limitations for the Amazon RDS (Microsoft SQL Server) connector
](rds-ms-sql-server-limitations.md)
+ [
# Amazon RDS (Microsoft SQL Server) connector overview
](rds-ms-sql-server-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Amazon RDS (Microsoft SQL Server)
](rds-ms-sql-server-prereqs.md)
+ [
# Connecting Amazon Q Business to Amazon RDS (Microsoft SQL Server) using the console
](rds-ms-sql-server-console.md)
+ [
# Connecting Amazon Q Business to Amazon RDS (Microsoft SQL Server) using APIs
](rds-ms-sql-server-api.md)
+ [
# How Amazon Q Business connector crawls Amazon RDS (Microsoft SQL Server) ACLs
](rds-ms-sql-server-user-management.md)
+ [
# Amazon RDS (Microsoft SQL Server) data source connector field mappings
](rds-ms-sql-server-field-mappings.md)
+ [
# IAM role for Amazon RDS (Microsoft SQL Server) connector
](rds-ms-sql-server-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Amazon RDS (Microsoft SQL Server) connector
Known limitations
+ Deleted database rows will not be tracked in when Amazon Q checks for updated content.
+ The size of field names and values in a row of your database can't exceed 400KB.
+ Column names should only contain alphanumeric characters and not spaces.
+ If you have a large amount of data in your database data source, and do not want Amazon Q to index all your database content after the first sync, you can choose to sync only new, modified, or deleted documents.
# Amazon RDS (Microsoft SQL Server) connector overview
Overview
The following table gives an overview of the Amazon Q Business Amazon RDS (Microsoft SQL Server) connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-ms-sql-server-overview.html)
# Prerequisites for connecting Amazon Q Business to Amazon RDS (Microsoft SQL Server)
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Amazon RDS (Microsoft SQL Server), make sure you have:**
+ Noted your database username and password.
**Important**
As a best practice, provide Amazon Q with read-only database credentials.
+ Copied your database host URL, port, and instance.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Amazon RDS (Microsoft SQL Server) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Amazon RDS (Microsoft SQL Server) using the console
Using the console
On the **Amazon RDS (Microsoft SQL Server)** page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
1. **Host** – Enter the database host name.
1. **Port** – Enter the database port.
1. **Instance** – Enter the database instance.
1. **SSL certificate location** – Choose to enter the Amazon S3 path to your SSL certificate file.
1. In **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. For **Database username**, and **Password** – Enter the authentication credential values you copied from your database.
1. Choose **Save**.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-ms-sql-server-connector.html#rds-ms-sql-server-iam).
1. In **Sync scope**, enter the following information:
+ **SQL query** – Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query.
+ **Primary key column** – Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data.
+ **Title column** – Provide the name of the column in your database table that you want to designate as the column with document titles.
+ **Body column** – Provide the name of the column in your database table that you want to designate as the column with document body text.
Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Additional configuration – *optional*** – Configure the following settings:
+ **Change-detecting columns** – Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns.
+ **Users' IDs column** – Enter the name of the column which contains User IDs to be allowed access to content.
+ **Groups column** – Enter the name of the column that contains groups to be allowed access to content.
+ **Source URLs column** – Enter the name of the column which contains Source URLs to be indexed.
+ **Time stamps column** – Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content.
+ **Time zones column** – Enter the name of the column which contains time zones for the content to be crawled.
+ **Time stamps format** – Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content.
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Amazon RDS (Microsoft SQL Server) using APIs
Using the API
You use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q Business application.
Then, you use the `configuration` parameter to provide a JSON schema with all other configuration information specific to your data source connector.
## Amazon RDS (Microsoft SQL Server) JSON schema
The following is the Amazon RDS (Microsoft SQL Server) JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"dbType": {
"type": "string",
"enum": [
"mysql",
"db2",
"postgresql",
"oracle",
"sqlserver"
]
},
"dbHost": {
"type": "string"
},
"dbPort": {
"type": "string"
},
"dbInstance": {
"type": "string"
}
},
"required": [
"dbType",
"dbHost",
"dbPort",
"dbInstance"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"document": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string"
},
"dataSourceFieldName": {
"type": "string"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
}
},
"required": [
]
},
"additionalProperties": {
"type": "object",
"properties": {
"primaryKey": {
"type": "string"
},
"titleColumn": {
"type": "string"
},
"bodyColumn": {
"type": "string"
},
"sqlQuery": {
"type": "string",
"not": {
"pattern": ";+"
}
},
"timestampColumn": {
"type": "string"
},
"timestampFormat": {
"type": "string"
},
"timezone": {
"type": "string"
},
"changeDetectingColumns": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedUsersColumn": {
"type": "string"
},
"allowedGroupsColumn": {
"type": "string"
},
"sourceURIColumn": {
"type": "string"
},
"serverlessAurora": {
"type": "string",
"enum": ["true", "false"]
}
},
"required": ["primaryKey", "titleColumn", "bodyColumn", "sqlQuery"]
},
"type" : {
"type" : "string",
"pattern": "JDBC"
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL"
]
},
"secretArn": {
"type": "string"
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | Required configuration information for connecting your data source.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-ms-sql-server-api.html) |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. Specify the type of data source and the secret ARN. |
| document | A list of objects that map the attributes or field names of your database content to Amazon Q index field names. For more information, see [Mapping data source fields](https://docs.aws.amazon.com/kendra/latest/dg/field-mapping.html). |
| additionalProperties | Additional configuration options for your content in your data source. Use to include or exclude specific content in your database data source. |
| primaryKey | Provide the primary key for the database table. This identifies a table within your database. |
| titleColumn | Provide the name of the document title column within your database table. |
| bodyColumn | Provide the name of the document title column within your database table. |
| sqlQuery | Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query. If a table name has special characters, put it in square brackets "[ ]" in the SQL query. For example: select \$1 from [my-database-table]. |
| timestampColumn | Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content. |
| timestampFormat | Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content. |
| timezone | Enter the name of the column which contains time zones for the content to be crawled. |
| changeDetectingColumns | Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns |
| allowedUsersColumns | Enter the name of the column which contains User IDs to be allowed access to content. |
| allowedGroupsColumn | Enter the name of the column which contains User IDs to be allowed access to content. |
| sourceURIColumn | Enter the name of the column which contains Source URLs to be indexed. |
| isSslEnabled | true to add a path to an SSL certificate file stored in an Amazon S3 bucket. |
| type | The type of data source. Specify JDBC as your data source type. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-ms-sql-server-api.html) |
| secretArn | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains user name and password required to connect to your database. The secret must contain a JSON structure with the following keys: {
"username": "database username",
"password": "password"
} |
| version | The version of the template that is currently supported. |
# How Amazon Q Business connector crawls Amazon RDS (Microsoft SQL Server) ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect a database data source to Amazon Q, Amazon Q crawls user and group information from a column in the source table. You specify this column in the console or using the `configuration` parameter as part of the `CreateDataSource` operation.
If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
A database data source has the following limitations:
+ You can only specify an allow list for a database data source. You can't specify a deny list.
+ You can only specify groups. You can't specify individual users for the allow list.
+ The database column should be a string containing a semicolon delimited list of groups.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Amazon RDS (Microsoft SQL Server) data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q PostgreSQL connector supports the following field mappings:
**Topics**
+ [
## Document
](#rds-ms-sql-server-field-mappings-document)
## Document
| JDBC field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| jd\$1document\$1id | jd\$1document\$1id | Custom | String |
| jd\$1document\$1title | jd\$1document\$1title | Custom | String |
| jd\$1source\$1uri | \$1source\$1uri | Default | String |
# IAM role for Amazon RDS (Microsoft SQL Server) connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Amazon RDS (MySQL) to Amazon Q Business
Amazon RDS (MySQL)
**Note**
Amazon RDS (MySQL) connector remains fully supported for existing customers through May 31, 2026. While this connector is no longer available for new users, current users can continue to use it without interruption. We are continuously evolving our connector portfolio to offer more scalable and customizable solutions. For future integrations, we recommend exploring the [Amazon Q Business Custom Connector Framework](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-connector.html), designed to support a broader range of enterprise use cases with enhanced flexibility.
Amazon RDS (MySQL) (Amazon Relational Database Service) is a web service that makes it easier to set up, operate, and scale a relational database in the AWS Cloud. You can connect your Amazon RDS (MySQL) instance to Amazon Q Business – using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API – and create an Amazon Q web experience.
The Amazon Q Aurora (MySQL) data source connector supports Amazon RDS MySql 5.6, 5.7, and 8.0.
**Important**
As a best practice, provide Amazon Q with read-only database credentials. Also, avoid adding tables with sensitive data or personal identifiable information (PII).
**Topics**
+ [
# Known limitations for the Amazon RDS (MySQL) connector
](rds-my-sql-limitations.md)
+ [
# Amazon RDS (MySQL) connector overview
](rds-my-sql-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Amazon RDS (MySQL)
](rds-my-sql-prereqs.md)
+ [
# Connecting Amazon Q Business to Amazon RDS (MySQL) using the console
](rds-my-sql-console.md)
+ [
# Connecting Amazon Q Business to Amazon RDS (MySQL) using APIs
](rds-my-sql-api.md)
+ [
# How Amazon Q Business connector crawls Amazon RDS (MySQL) ACLs
](rds-my-sql-user-management.md)
+ [
# Amazon RDS (MySQL) data source connector field mappings
](rds-my-sql-field-mappings.md)
+ [
# IAM role for Amazon RDS (MySQL) connector
](rds-my-sql-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Amazon RDS (MySQL) connector
Known limitations
The Amazon RDS (MySQL) connector has the following known limitations:
+ Deleted database rows will not be tracked in when Amazon Q checks for updated content.
+ The size of field names and values in a row of your database can't exceed 400KB.
+ Column names should only contain alphanumeric characters and not spaces.
+ If you have a large amount of data in your database data source, and do not want Amazon Q to index all your database content after the first sync, you can choose to sync only new, modified, or deleted documents.
# Amazon RDS (MySQL) connector overview
Overview
The following table gives an overview of the Amazon Q Business Amazon RDS (MySQL) connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-my-sql-overview.html)
# Prerequisites for connecting Amazon Q Business to Amazon RDS (MySQL)
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Amazon RDS (MySQL), make sure you have:**
+ Noted your database username and password.
**Important**
As a best practice, provide Amazon Q with read-only database credentials.
+ Copied your database host URL, port, and instance. You can find this information on the Amazon RDS console.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Amazon RDS (MySQL) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Amazon RDS (MySQL) using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Amazon RDS (MySQL) using the AWS Management Console.
**Connecting Amazon Q to Amazon RDS (MySQL)**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Amazon RDS (MySQL)** data source to your Amazon Q application.
1. Then, on the **Amazon RDS (MySQL)** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
1. **Host** – Enter the database host URL, for example: `http://instance URL.region.rds.amazonaws.com`.
1. **Port** – Enter the database port, for example, `3306`.
1. **Instance** – Enter the database instance, for example `mysql`.
1. **SSL certificate location** – Choose to enter the Amazon S3 path to your SSL certificate file.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. In **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. For **Database username**, and **Password** – Enter the authentication credential values you copied from your database.
1. Choose **Save**.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-my-sql-connector.html#rds-my-sql-iam).
1. In **Sync scope**, enter the following information:
+ **SQL query** – Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query.
+ **Primary key column** – Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data.
+ **Title column** – Provide the name of the column in your database table that you want to designate as the column with document titles.
+ **Body column** – Provide the name of the column in your database table that you want to designate as the column with document body text.
Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Additional configuration – *optional*** – Configure the following settings:
+ **Change-detecting columns** – Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns.
+ **Users' IDs column** – Enter the name of the column which contains User IDs to be allowed access to content.
+ **Groups column** – Enter the name of the column that contains groups to be allowed access to content.
+ **Source URLs column** – Enter the name of the column which contains Source URLs to be indexed.
+ **Time stamps column** – Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content.
+ **Time zones column** – Enter the name of the column which contains time zones for the content to be crawled.
+ **Time stamps format** – Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content.
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Amazon RDS (MySQL) using APIs
Using the API
You use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application.
Then, you use the `configuration` parameter to provide a JSON schema with all other configuration information specific to your data source connector.
## Amazon RDS (MySQL) JSON schema
The following is the Amazon RDS (MySQL) JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"dbType": {
"type": "string",
"enum": [
"mysql",
"db2",
"postgresql",
"oracle",
"sqlserver"
]
},
"dbHost": {
"type": "string"
},
"dbPort": {
"type": "string"
},
"dbInstance": {
"type": "string"
}
},
"required": [
"dbType",
"dbHost",
"dbPort",
"dbInstance"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"document": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string"
},
"dataSourceFieldName": {
"type": "string"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
}
},
"required": [
]
},
"additionalProperties": {
"type": "object",
"properties": {
"primaryKey": {
"type": "string"
},
"titleColumn": {
"type": "string"
},
"bodyColumn": {
"type": "string"
},
"sqlQuery": {
"type": "string",
"not": {
"pattern": ";+"
}
},
"timestampColumn": {
"type": "string"
},
"timestampFormat": {
"type": "string"
},
"timezone": {
"type": "string"
},
"changeDetectingColumns": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedUsersColumn": {
"type": "string"
},
"allowedGroupsColumn": {
"type": "string"
},
"sourceURIColumn": {
"type": "string"
},
"serverlessAurora": {
"type": "string",
"enum": ["true", "false"]
}
},
"required": ["primaryKey", "titleColumn", "bodyColumn", "sqlQuery"]
},
"type" : {
"type" : "string",
"pattern": "JDBC"
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL",
"CHANGE_LOG"
]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | Required configuration information for connecting your data source.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-my-sql-api.html) |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. Specify the type of data source and the secret ARN. |
| document | A list of objects that map the attributes or field names of your database content to Amazon Q index field names. For more information, see [Fiel](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings). |
| additionalProperties | Additional configuration options for your content in your data source. Use to include or exclude specific content in your database data source. |
| primaryKey | Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data. |
| titleColumn | Provide the name of the column in your database table that you want to designate as the column with document titles. |
| bodyColumn | Provide the name of the column in your database table that you want to designate as the column with document body text. Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias. |
| sqlQuery | Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query. |
| timestampColumn | Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content. |
| timestampFormat | Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content. |
| timezone | Enter the name of the column which contains time zones for the content to be crawled. |
| changeDetectingColumns | Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns |
| allowedUsersColumns | Enter the name of the column which contains User IDs to be allowed access to content. |
| allowedGroupsColumn | Enter the name of the column which contains User IDs to be allowed access to content. |
| sourceURIColumn | Enter the name of the column which contains Source URLs to be indexed. |
| isSslEnabled | true to add a path to an SSL certificate file stored in an Amazon S3 bucket. |
| type | The type of data source. Specify JDBC as your data source type. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-my-sql-api.html) |
| secretArn | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains username and password required to connect to your database. The secret must contain a JSON structure with the following keys: {
"username": "database username",
"password": "password"
} |
| version | The version of the template that is currently supported. |
# How Amazon Q Business connector crawls Amazon RDS (MySQL) ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect a database data source to Amazon Q, Amazon Q crawls user and group information from a column in the source table. You specify this column in the console or using the `configuration` parameter as part of the `CreateDataSource` operation.
If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
A database data source has the following limitations:
+ You can only specify an allow list for a database data source. You can't specify a deny list.
+ You can only specify groups. You can't specify individual users for the allow list.
+ The database column should be a string containing a semicolon delimited list of groups.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Amazon RDS (MySQL) data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q PostgreSQL connector supports the following field mappings:
**Topics**
+ [
## Document
](#rds-my-sql-field-mappings-document)
## Document
| JDBC field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| jd\$1document\$1id | jd\$1document\$1id | Custom | String |
| jd\$1document\$1title | jd\$1document\$1title | Custom | String |
| jd\$1source\$1uri | \$1source\$1uri | Default | String |
# IAM role for Amazon RDS (MySQL) connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Amazon RDS (Oracle) to Amazon Q Business
Amazon RDS (Oracle)
**Note**
Amazon RDS (Oracle) connector remains fully supported for existing customers through May 31, 2026. While this connector is no longer available for new users, current users can continue to use it without interruption. We are continuously evolving our connector portfolio to offer more scalable and customizable solutions. For future integrations, we recommend exploring the [Amazon Q Business Custom Connector Framework](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-connector.html), designed to support a broader range of enterprise use cases with enhanced flexibility.
Amazon RDS (Oracle) (Amazon Relational Database Service) is a web service that makes it easier to set up, operate, and scale a relational database in the AWS Cloud. You can connect your Amazon RDS (Oracle) instance to Amazon Q Business – using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API – and create an Amazon Q web experience.
The Amazon RDS (Oracle) (Amazon Relational Database Service) data source connector supports Amazon RDS Oracle Database 21c, Oracle Database 19c, Oracle Database 12c.
**Important**
As a best practice, provide Amazon Q with read-only database credentials. Also, avoid adding tables with sensitive data or personal identifiable information (PII).
**Topics**
+ [
# Known limitations for the Amazon RDS (Oracle) connector
](rds-oracle-limitations.md)
+ [
# Amazon RDS (Oracle) connector overview
](rds-oracle-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Amazon RDS (Oracle)
](rds-oracle-prereqs.md)
+ [
# Connecting Amazon Q Business to Amazon RDS (Oracle) using the console
](rds-oracle-console.md)
+ [
# Connecting Amazon Q Business to Amazon RDS (Oracle) using APIs
](rds-oracle-api.md)
+ [
# How Amazon Q Business connector crawls Amazon RDS (Oracle) ACLs
](rds-oracle-user-management.md)
+ [
# Amazon RDS (Oracle) data source connector field mappings
](rds-oracle-field-mappings.md)
+ [
# IAM role for Amazon RDS (Oracle) connector
](rds-oracle-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Amazon RDS (Oracle) connector
Known limitations
The Amazon RDS (Oracle) connector has the following known limitations:
+ Deleted database rows will not be tracked in when Amazon Q checks for updated content.
+ The size of field names and values in a row of your database can't exceed 400KB.
+ Column names should only contain alphanumeric characters and not spaces.
+ If you have a large amount of data in your database data source, and do not want Amazon Q to index all your database content after the first sync, you can choose to sync only new, modified, or deleted documents.
# Amazon RDS (Oracle) connector overview
Overview
The following table gives an overview of the Amazon Q Business Amazon RDS (Oracle) connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-oracle-overview.html)
# Prerequisites for connecting Amazon Q Business to Amazon RDS (Oracle)
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Amazon RDS (Oracle), make sure you have:**
+ Noted your database username and password.
**Important**
As a best practice, provide Amazon Q with read-only database credentials.
+ Copied your database host URL, port, and instance.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Amazon RDS (Oracle) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Amazon RDS (Oracle) using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Amazon RDS (Oracle) using the AWS Management Console.
**Connecting Amazon Q to Amazon RDS (Oracle)**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Amazon RDS (Oracle)** data source to your Amazon Q application.
1. Then, on the **Amazon RDS (Oracle)** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. **Source**, enter the following information:
1. **Host** – Enter the database host name.
1. **Port** – Enter the database port.
1. **Instance** – Enter the database instance.
1. **SSL certificate location** – Choose to enter the Amazon S3 path to your SSL certificate file.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. In **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. For **Database username**, and **Password** – Enter the authentication credential values you copied from your database.
1. Choose **Save**.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-oracle-connector.html#rds-oracle-iam).
1. In **Sync scope**, enter the following information:
+ **SQL query** – Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query.
+ **Primary key column** – Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data.
+ **Title column** – Provide the name of the column in your database table that you want to designate as the column with document titles.
+ **Body column** – Provide the name of the column in your database table that you want to designate as the column with document body text.
Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Additional configuration – *optional*** – Configure the following settings:
+ **Change-detecting columns** – Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns.
+ **Users' IDs column** – Enter the name of the column which contains User IDs to be allowed access to content.
+ **Groups column** – Enter the name of the column that contains groups to be allowed access to content.
+ **Source URLs column** – Enter the name of the column which contains Source URLs to be indexed.
+ **Time stamps column** – Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content.
+ **Time zones column** – Enter the name of the column which contains time zones for the content to be crawled.
+ **Time stamps format** – Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content.
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Amazon RDS (Oracle) using APIs
Using the API
You use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application.
Then, you use the `configuration` parameter to provide a JSON schema with all other configuration information specific to your data source connector.
## Amazon RDS (Oracle) JSON schema
The following is the Amazon RDS (Oracle) JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"dbType": {
"type": "string",
"enum": [
"mysql",
"db2",
"postgresql",
"oracle",
"sqlserver"
]
},
"dbHost": {
"type": "string"
},
"dbPort": {
"type": "string"
},
"dbInstance": {
"type": "string"
}
},
"required": [
"dbType",
"dbHost",
"dbPort",
"dbInstance"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"document": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string"
},
"dataSourceFieldName": {
"type": "string"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
}
},
"required": [
]
},
"additionalProperties": {
"type": "object",
"properties": {
"primaryKey": {
"type": "string"
},
"titleColumn": {
"type": "string"
},
"bodyColumn": {
"type": "string"
},
"sqlQuery": {
"type": "string",
"not": {
"pattern": ";+"
}
},
"timestampColumn": {
"type": "string"
},
"timestampFormat": {
"type": "string"
},
"timezone": {
"type": "string"
},
"changeDetectingColumns": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedUsersColumn": {
"type": "string"
},
"allowedGroupsColumn": {
"type": "string"
},
"sourceURIColumn": {
"type": "string"
},
"serverlessAurora": {
"type": "string",
"enum": ["true", "false"]
}
},
"required": ["primaryKey", "titleColumn", "bodyColumn", "sqlQuery"]
},
"type" : {
"type" : "string",
"pattern": "JDBC"
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL",
"CHANGE_LOG"
]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | Required configuration information for connecting your data source.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-oracle-api.html) |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. Specify the type of data source and the secret ARN. |
| document | A list of objects that map the attributes or field names of your database content to Amazon Q index field names. For more information, see [Fiel](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings). |
| additionalProperties | Additional configuration options for your content in your data source. Use to include or exclude specific content in your database data source. |
| primaryKey | Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data. |
| titleColumn | Provide the name of the column in your database table that you want to designate as the column with document titles. |
| bodyColumn | Provide the name of the column in your database table that you want to designate as the column with document body text. Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias. |
| sqlQuery | Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query. |
| timestampColumn | Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content. |
| timestampFormat | Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content. |
| timezone | Enter the name of the column which contains time zones for the content to be crawled. |
| changeDetectingColumns | Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns |
| allowedUsersColumns | Enter the name of the column which contains User IDs to be allowed access to content. |
| allowedGroupsColumn | Enter the name of the column which contains User IDs to be allowed access to content. |
| sourceURIColumn | Enter the name of the column which contains Source URLs to be indexed. |
| isSslEnabled | true to add a path to an SSL certificate file stored in an Amazon S3 bucket. |
| type | The type of data source. Specify JDBC as your data source type. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-oracle-api.html) |
| secretArn | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains username and password required to connect to your database. The secret must contain a JSON structure with the following keys: {
"username": "database username",
"password": "password"
} |
| version | The version of the template that is currently supported. |
# How Amazon Q Business connector crawls Amazon RDS (Oracle) ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect a database data source to Amazon Q, Amazon Q crawls user and group information from a column in the source table. You specify this column in the console or using the `configuration` parameter as part of the `CreateDataSource` operation.
If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
A database data source has the following limitations:
+ You can only specify an allow list for a database data source. You can't specify a deny list.
+ You can only specify groups. You can't specify individual users for the allow list.
+ The database column should be a string containing a semicolon delimited list of groups.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Amazon RDS (Oracle) data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q PostgreSQL connector supports the following field mappings:
**Topics**
+ [
## Document
](#rds-oracle-field-mappings-document)
## Document
| JDBC field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| jd\$1document\$1id | jd\$1document\$1id | Custom | String |
| jd\$1document\$1title | jd\$1document\$1title | Custom | String |
| jd\$1source\$1uri | \$1source\$1uri | Default | String |
# IAM role for Amazon RDS (Oracle) connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Amazon RDS (PostgreSQL) to Amazon Q Business
Amazon RDS (PostgreSQL)
**Note**
Amazon RDS (PostgreSQL) connector remains fully supported for existing customers through May 31, 2026. While this connector is no longer available for new users, current users can continue to use it without interruption. We are continuously evolving our connector portfolio to offer more scalable and customizable solutions. For future integrations, we recommend exploring the [Amazon Q Business Custom Connector Framework](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/custom-connector.html), designed to support a broader range of enterprise use cases with enhanced flexibility.
Amazon RDS (PostgreSQL) is a web service that makes it easier to set up, operate, and scale a relational database in the AWS Cloud. If you are a AWS user, you can use Amazon Q Business to index your Amazon RDS (PostgreSQL) data source.
The Amazon Q Amazon RDS (PostgreSQL) data source connector supports PostgreSQL 9.6.
You can connect your Amazon RDS (PostgreSQL) instance to Amazon Q Business—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Important**
As a best practice, provide Amazon Q with read-only database credentials. Also, avoid adding tables with sensitive data or personal identifiable information (PII).
**Topics**
+ [
# Known limitations for the Amazon RDS (PostgreSQL) connector
](rds-postgresql-limitations.md)
+ [
# Amazon RDS (PostgreSQL) connector overview
](rds-postgresql-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Amazon RDS (PostgreSQL)
](rds-postgresql-prereqs.md)
+ [
# Connecting Amazon Q Business to Amazon RDS (PostgreSQL) using the console
](rds-postgresql-console.md)
+ [
# Connecting Amazon Q Business to Amazon RDS (PostgreSQL) using APIs
](rds-postgresql-api.md)
+ [
# How Amazon Q Business connector crawls Amazon RDS (PostgreSQL) ACLs
](rds-postgresql-user-management.md)
+ [
# Amazon RDS (PostgreSQL) data source connector field mappings
](rds-postgresql-field-mappings.md)
+ [
# IAM role for Amazon RDS (PostgreSQL) connector
](rds-postgresql-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Amazon RDS (PostgreSQL) connector
Known limitations
The Amazon RDS (PostgreSQL) connector has the following known limitations:
+ Deleted database rows will not be tracked in when Amazon Q checks for updated content.
+ The size of field names and values in a row of your database can't exceed 400KB.
+ Column names should only contain alphanumeric characters and not spaces.
+ If you have a large amount of data in your database data source, and do not want Amazon Q to index all your database content after the first sync, you can choose to sync only new, modified, or deleted documents.
# Amazon RDS (PostgreSQL) connector overview
Overview
The following table gives an overview of the Amazon RDS (PostgreSQL) connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-postgresql-overview.html)
# Prerequisites for connecting Amazon Q Business to Amazon RDS (PostgreSQL)
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Amazon RDS (PostgreSQL), make sure you have:**
+ Noted your database username and password.
**Important**
As a best practice, provide Amazon Q with read-only database credentials.
+ Copied your database host URL, port, and instance. You can find this information on the Amazon RDS console.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Amazon RDS (PostgreSQL) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Amazon RDS (PostgreSQL) using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Amazon RDS (PostgreSQL) using the AWS Management Console.
**Connecting Amazon Q to Amazon RDS (PostgreSQL)**
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
1. **Host** – Enter the database host URL, for example: `http://instance URL.region.rds.amazonaws.com`.
1. **Port** – Enter the database port, for example, `5432`.
1. **Instance** – Enter the database instance, for example `postgres` .
1. **SSL certificate location** – Choose to enter the Amazon S3 path to your SSL certificate file.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. In **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. For **Database username**, and **Password** – Enter the authentication credential values you copied from your database.
1. Choose **Save**.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-postgresql-connector.html#rds-postgresql-iam).
1. In **Sync scope**, enter the following information:
+ **SQL query** – Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query.
+ **Primary key column** – Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data.
+ **Title column** – Provide the name of the column in your database table that you want to designate as the column with document titles.
+ **Body column** – Provide the name of the column in your database table that you want to designate as the column with document body text.
Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Additional configuration – *optional*** – Configure the following settings:
+ **Change-detecting columns** – Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns.
+ **Users' IDs column** – Enter the name of the column which contains User IDs to be allowed access to content.
+ **Groups column** – Enter the name of the column that contains groups to be allowed access to content.
+ **Source URLs column** – Enter the name of the column which contains Source URLs to be indexed.
+ **Time stamps column** – Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content.
+ **Time zones column** – Enter the name of the column which contains time zones for the content to be crawled.
+ **Time stamps format** – Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content.
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Amazon RDS (PostgreSQL) using APIs
Using the API
You use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application.
Then, you use the `configuration` parameter to provide a JSON schema with all other configuration information specific to your data source connector.
## Amazon RDS (PostgreSQL) JSON schema
The following is the Amazon RDS (PostgreSQL) JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"dbType": {
"type": "string",
"enum": [
"mysql",
"db2",
"postgresql",
"oracle",
"sqlserver"
]
},
"dbHost": {
"type": "string"
},
"dbPort": {
"type": "string"
},
"dbInstance": {
"type": "string"
}
},
"required": [
"dbType",
"dbHost",
"dbPort",
"dbInstance"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"document": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string"
},
"dataSourceFieldName": {
"type": "string"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
}
},
"required": [
]
},
"additionalProperties": {
"type": "object",
"properties": {
"primaryKey": {
"type": "string"
},
"titleColumn": {
"type": "string"
},
"bodyColumn": {
"type": "string"
},
"sqlQuery": {
"type": "string",
"not": {
"pattern": ";+"
}
},
"timestampColumn": {
"type": "string"
},
"timestampFormat": {
"type": "string"
},
"timezone": {
"type": "string"
},
"changeDetectingColumns": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedUsersColumn": {
"type": "string"
},
"allowedGroupsColumn": {
"type": "string"
},
"sourceURIColumn": {
"type": "string"
},
"serverlessAurora": {
"type": "string",
"enum": ["true", "false"]
}
},
"required": ["primaryKey", "titleColumn", "bodyColumn", "sqlQuery"]
},
"type" : {
"type" : "string",
"pattern": "JDBC"
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL",
"CHANGE_LOG"
]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | Required configuration information for connecting your data source.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-postgresql-api.html) |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. Specify the type of data source and the secret ARN. |
| document | A list of objects that map the attributes or field names of your database content to Amazon Q index field names. For more information, see [Fiel](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings). |
| additionalProperties | Additional configuration options for your content in your data source. Use to include or exclude specific content in your database data source. |
| primaryKey | Provide the primary key for the database table. This identifies the row in the table for which your SQL query is written. The connector uses the primary key column value to identify rows, detect changes, and crawl data. |
| titleColumn | Provide the name of the column in your database table that you want to designate as the column with document titles. |
| bodyColumn | Provide the name of the column in your database table that you want to designate as the column with document body text. Your SQL query can include multiple columns in your table concatenated into a single body column with an assigned alias. |
| sqlQuery | Enter SQL query statements like SELECT and JOIN operations. SQL queries must be less than 1000 characters and not contain any semi-colons (;). Amazon Q will crawl all database content that matches your query. |
| timestampColumn | Enter the name of the column which contains time stamps. Amazon Q uses time stamp information to detect changes in your content and sync only changed content. |
| timestampFormat | Enter the name of the column which contains time stamp formats to use to detect content changes and re-sync your content. |
| timezone | Enter the name of the column which contains time zones for the content to be crawled. |
| changeDetectingColumns | Enter the names of the columns that Amazon Q will use to detect content changes. Amazon Q will re-index content when there is a change in any of these columns |
| allowedUsersColumns | Enter the name of the column which contains User IDs to be allowed access to content. |
| allowedGroupsColumn | Enter the name of the column which contains User IDs to be allowed access to content. |
| sourceURIColumn | Enter the name of the column which contains Source URLs to be indexed. |
| isSslEnabled | true to add a path to an SSL certificate file stored in an Amazon S3 bucket. |
| type | The type of data source. Specify JDBC as your data source type. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/rds-postgresql-api.html) |
| secretArn | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains username and password required to connect to your database. The secret must contain a JSON structure with the following keys: {
"username": "database username",
"password": "password"
} |
| version | The version of the template that is currently supported. |
# How Amazon Q Business connector crawls Amazon RDS (PostgreSQL) ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect a database data source to Amazon Q, Amazon Q crawls user and group information from a column in the source table. You specify this column in the console or using the `configuration` parameter as part of the `CreateDataSource` operation.
If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
A database data source has the following limitations:
+ You can only specify an allow list for a database data source. You can't specify a deny list.
+ You can only specify groups. You can't specify individual users for the allow list.
+ The database column should be a string containing a semicolon delimited list of groups.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Amazon RDS (PostgreSQL) data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q PostgreSQL connector supports the following field mappings:
**Topics**
+ [
## Document
](#rds-postgresql-field-mappings-document)
## Document
| JDBC field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| jd\$1document\$1id | jd\$1document\$1id | Custom | String |
| jd\$1document\$1title | jd\$1document\$1title | Custom | String |
| jd\$1source\$1uri | \$1source\$1uri | Default | String |
# IAM role for Amazon RDS (PostgreSQL) connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Amazon Q custom connector to Amazon Q Business
Amazon Q custom connector
Use a custom data source when you have a repository that Amazon Q Business doesn’t yet provide a data source connector for. When you create a custom data source, you have complete control over how the documents to index are selected. Amazon Q only provides metric information that you can use to monitor your data source sync jobs. You must create and run the crawler that determines the documents your data source indexes.
**You can use a custom data source connector to:**
+ See the same run history metrics that Amazon Q data sources provide even when you can't use Amazon Q data sources to sync your repositories.
+ Create a consistent sync monitoring experience between Amazon Q data sources and custom data sources.
+ See sync metrics for a data source connector that you created using the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchPutDocument.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchPutDocument.html) and [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchDeleteDocument.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchDeleteDocument.html) API operations.
You can create an Amazon Q custom data source connector using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html).
**When you create a custom data source using the `CreateDataSource` API operation:**
+ The action returns an ID to use when you synchronize the data source.
+ You only need to provide a `Name` and optionally a `Description`.
+ Set the `Configuration` parameter as follows:
```
"configuration": {
"type": "CUSTOM",
"version": "1.0.0"
}
```
+ When indexing documents later, you must specify the main title of your documents using the [Document](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_Document.html) object, and `_source_uri` in [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttribute.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttribute.html). The main title is required so that `DocumentTitle` and `DocumentURI` are included in the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ChatSync.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ChatSync.html) or [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_Chat.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_Chat.html) response.
**When you create a custom data source using the console:**
+ The console returns an ID to use when you synchronize the data source.
+ Give your data source a name, and optionally a description and resource tags.
+ After the data source is created, a data source ID is shown. Copy this ID to use when you synchronize the data source with the index.
**Topics**
+ [
# Creating an Amazon Q custom connector
](custom-connector-hiw.md)
+ [
# Required attributes
](custom-required-attributes.md)
+ [
# Viewing metrics
](custom-metrics.md)
# Creating an Amazon Q custom connector
To use a custom data source, create an application environment that is responsible for updating your Amazon Q index. The application environment depends on a crawler that you create. The crawler reads the documents in your repository and determines which documents should be sent to Amazon Q. Your application environment should perform the following steps:
1. Crawl your repository and make a list of the documents in your repository that are added, updated, or deleted.
1. Call the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_StartDataSourceSyncJob.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_StartDataSourceSyncJob.html) API operation to signal that a sync job is starting. You provide a data source ID to identify the data source that is synchronizing. Amazon Q returns an execution ID to identify a particular sync job.
**Note**
After you end a sync job, you can start a new sync job. There can be a period of time before all of the submitted documents are added to the index. To see the status of the sync job, use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListDataSourceSyncJobs.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListDataSourceSyncJobs.html) operation. If the `Status` returned for the sync job is `SYNCING_INDEXING`, some documents are still being indexed. You can start a new sync job when the status of the previous job is `FAILED` or `SUCCEEDED`.
1. To remove documents from the index, use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchDeleteDocument.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchDeleteDocument.html) operation. You provide the data source ID and execution ID to identify the data source that is synchronizing and the job that this update is associated with.
1. To signal the end of the sync job, use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_StopDataSourceSyncJob.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_StopDataSourceSyncJob.html) operation. After you call the `StopDataSourceSyncJob` operation, the associated execution ID is no longer valid.
**Note**
After you call the `StopDataSourceSyncJob` operation, you can't use a sync job identifier in a call to the `BatchPutDocument` or `BatchDeleteDocument` operations. If you do, all of the documents submitted are returned in the `FailedDocuments` response message from the API.
1. To list the sync jobs for the data source and to see metrics for the sync jobs, use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListDataSourceSyncJobs.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListDataSourceSyncJobs.html) operation with the index and data source identifiers.
# Required attributes
When you submit a document to Amazon Q using the `BatchPutDocument` API operation, you must provide the following two attributes for each document:
+ `_data_source_id` – The identifier of the data source. This is returned when you create the data source with either the console or the `CreateDataSource` API operation.
+ `_data_source_sync_job_execution_id` – The identifier of the sync run. This is returned when you start the index synchronization with the `StartDataSourceSyncJob` operation.
The following is the JSON required to index a document using a custom data source.
```
{
"Documents": [
{
"Attributes": [
{
"Key": "_data_source_id",
"Value": {
"StringValue": "data source identifier"
}
},
{
"Key": "_data_source_sync_job_execution_id",
"Value": {
"StringValue": "sync job identifier"
}
}
],
"Blob": "document content",
"ContentType": "content type",
"Id": "document identifier",
"Title": "document title"
}
],
"IndexId": "index identifier",
"RoleArn": "IAM role ARN"
}
```
When you remove a document from the index using the `BatchDeleteDocument` API operation, you must specify the following two fields in the `DataSourceSyncJobMetricTarget` parameter:
+ `DataSourceId` – The identifier of the data source. This is returned when you create the data source with either the console or the `CreateDataSource` API operation.
+ `DataSourceSyncJobId` – The identifier of the sync run. This is returned when you start the index synchronization with the `StartDataSourceSyncJob` operation.
The following is the JSON required to delete a document from the index using the `BatchDeleteDocument` operation.
```
{
"DataSourceSyncJobMetricTarget": {
"DataSourceId": "data source identifier",
"DataSourceSyncJobId": "sync job identifier"
},
"DocumentIdList": [
"document identifier"
],
"IndexId": "index identifier"
}
```
# Viewing metrics
After a sync job is finished, you can use the `DataSourceSyncJobMetrics` API operation to get the metrics associated with the sync job. Use this API operation to monitor your custom data source syncs.
You can submit the same document multiple times, either as part of the `BatchPutDocument` operation, the `BatchDeleteDocument` operation, or if the document is submitted for both addition and deletion, Regardless of how you submit the document, it is only counted once in the metrics.
+ `DocumentsAdded` – The number of documents submitted using the `BatchPutDocument` operation associated with this sync job that are added to the index for the first time. If a document is submitted for addition more than once in a sync, the document is only counted once in the metrics.
+ `DocumentsDeleted` – The number of documents submitted using the `BatchDeleteDocument` operation associated with this sync job that are deleted from the index. If a document is submitted for deletion more than once in a sync, the document is only counted once in the metrics.
+ `DocumentsFailed` – The number of documents associated with this sync job that failed indexing. These documents were accepted by Amazon Q for indexing but could not be indexed or deleted. If a document isn't accepted by Amazon Q, the identifier for the document is returned in the `FailedDocuments` response property of the `BatchPutDocument` and `BatchDeleteDocument` operations.
+ `DocumentsModified` – The number of modified documents submitted using the `BatchPutDocument` operation associated with this sync job that were modified in the Amazon Q index.
Amazon Q also emits Amazon CloudWatch metrics while indexing documents. For more information, see [Monitoring Amazon Q with Amazon CloudWatch](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/monitoring-cloudwatch.html).
Amazon Q doesn't return the `DocumentsScanned` metric for custom data sources.
# Connecting Web Crawler to Amazon Q Business
Amazon Q Web Crawler
An Amazon Q Business Web Crawler connector crawls and indexes either public facing websites or internal company websites that use HTTPS. With Amazon Q web crawler, you can create a generative AI web experience for your end users based on the website data you crawl using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API.
**Note**
Amazon Q Web Crawler supports only HTTPS enabled sites. It doesn't support HTTP or self-signed certificate enabled websites.
**Important**
When selecting websites to index, you must adhere to the [Amazon Acceptable Use Policy](https://aws.amazon.com/aup/) and all other Amazon terms. Remember that you must only use Amazon Q Web Crawler to index your own webpages, or webpages that you have authorization to index. To learn how to stop Amazon Q Web Crawler from indexing your websites, see [Configuring a `robots.txt` file for Amazon Q Business Web Crawler](stop-web-crawler.md).
If you receive an error when crawling a website, it could be that the website is blocked from crawling. To crawl internal websites, you can set up a web proxy. The web proxy must be public facing. You can also use authentication to access and crawl websites.
**Note**
Amazon Q Web Crawler connector does *not* support AWS KMS encrypted Amazon S3 buckets. It supports only server-side encryption with Amazon S3 managed keys.
**Topics**
+ [
# Web Crawler connector overview
](webcrawler-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Web Crawler
](webcrawler-prereqs.md)
+ [
# Retrieving XPaths (XML Path Language) for Web Crawler
](webcrawler-retrieving-credentials.md)
+ [
# Connecting Amazon Q Business to Web Crawler using the console
](webcrawler-console.md)
+ [
# Connecting Amazon Q Business to Web Crawler using APIs
](web-crawler-api.md)
+ [
# Connecting Amazon Q Business to Web Crawler using AWS CloudFormation
](web-crawler-cfn.md)
+ [
# Web Crawler data source connector field mappings
](web-crawler-field-mappings.md)
+ [
# IAM role for Amazon Q Business Web Crawler connector
](webcrawler-iam-role.md)
+ [
# Configuring a `robots.txt` file for Amazon Q Business Web Crawler
](stop-web-crawler.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Web Crawler connector overview
Overview
The following table gives an overview of the Amazon Q Business Web Crawler connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/webcrawler-overview.html)
# Prerequisites for connecting Amazon Q Business to Web Crawler
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**Note**
For more information on connecting Web Crawler to Amazon Q Business, see [Index website contents using the Amazon Q Web Crawler connector for Amazon Q Business](https://aws.amazon.com/blogs/machine-learning/index-website-contents-using-the-amazon-q-web-crawler-connector-for-amazon-q-business/) in the *AWS Machine Learning Blog*.
**For Amazon Q Web Crawler, make sure you have:**
+ Copied the seed or sitemap URLs of the websites that you want to index and stored them in a text file or an Amazon S3 bucket. Each URL must be included on a separate line.
+ **For XML sitemaps:** Copied the sitemap XML and saved it in an XML file in an Amazon S3 bucket. You can also combine multiple sitemap XML files into a .zip file.
+ **For websites that require basic, NTLM, or Kerberos authentication:**
+ Noted your website authentication credentials, which include a username and password.
**Note**
Amazon Q Web Crawler supports the NTLM authentication protocol that includes password hashing, and Kerberos authentication protocol that includes password encryption.
+ **For websites that require SAML or login form authentication:**
+ Noted your website authentication credentials, which include a username and password.
+ Copied the XPaths (XML Path Language) of the username field (and the username button if using SAML), password field and button, and copied the login page URL. You can find the XPaths of elements using your web browser’s developer tools. XPaths follow this format: `//tagname[@Attribute='Value']`.
**Note**
Amazon Q Web Crawler uses a headless Chrome browser and the information from the form to authenticate and authorize access with an OAuth 2.0 protected URL.
+ **Optional:** Copied the host name and the port number of the web proxy server if you want to use a web proxy to connect to internal websites that you want to crawl. The web proxy must be public facing. Amazon Q supports connecting to web proxy servers backed by basic authentication, or you can connect with no authentication.
+ **Optional:** Copied the virtual private cloud (VPC) subnet ID if you want to use a VPC to connect to internal websites you want to crawl. For more information, see [Using Amazon VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-vpc.html).
**In your AWS account, make sure you have:**
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the API, noted the ARN of the IAM role.
+ **For websites that require authentication credentials to crawl:** Stored your Web Crawler authentication credentials in an AWS Secrets Manager secret and, if using the API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application environment on the console.
# Retrieving XPaths (XML Path Language) for Web Crawler
Retrieving XPaths
If the website you are crawling with Amazon Q Business Web Crawler uses Form or SAML authentication, you need to provide Amazon Q with the absolute XPaths for the username and password fields on your web page. Optionally, you may also need to provide the absolute XPaths to the username and password buttons.
XPaths are expressions used to uniquely identify and locate the content of any XML like language document (including HTML). Amazon Q uses the XPaths you provide to confirm access to the website you want to crawl. XPaths usually follow the following format: `//tagname[@Attribute='Value']`.
The following tabs provide a procedure for retrieving XPaths required for your Amazon Q Web Crawler connector using different web browsers.
------
#### [ Chrome ]
**To retrieve XPaths for an Amazon Q Web Crawler**
1. Make sure you're on the web page you want to crawl. Then, either select or click on the web page element you want to retrieve the XPath for. This could be the username or password fields, or the username and password buttons.
1. Then, open the context (right-click) menu and then choose the **Inspect** option.
![\[Screenshot showing how to use browser developer tools to inspect an HTML element for extracting its XPath. The image highlights the element selection process in the developer tools interface.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/xpath-1.png)
In the **Developer Tools** window that opens, the details for the element you've chosen will be highlighted.
1. Right click on the highlighted element to open the context (right-click) menu.
1. Choose **Copy**.
1. Then, choose **Copy XPath**.
![\[Screenshot showing the context menu in browser developer tools with the "Copy XPath" option highlighted, demonstrating how to copy the XPath of a selected HTML element.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/xpath-2.png)
1. Then, open a text editor of your choice and paste the XPath you copied. The format of the XPath will look like this: `//tagname[@Attribute='Value']`.
Input the relevant XPaths you've copied in the **Authentication** section when you configure Amazon Q Web Crawler connector.
------
#### [ Firefox ]
**To retrieve XPaths for an Amazon Q Web Crawler**
1. Make sure you're on the web page you want to crawl. Then, either select or click on the web page element you want to retrieve the XPath for. This could be the username or password fields, or the username and password buttons.
1. Then, open the context (right-click) menu and then choose the **Inspect** option.
![\[Screenshot showing another example of using browser developer tools to inspect an HTML element, with the element properties panel visible on the right side.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/xpath-3.png)
In the **Developer Tools** window that opens, the details for the element you've chosen will be highlighted.
1. Right click on the highlighted element to open the context (right-click) menu.
1. Choose **Copy**.
1. Then, choose **Copy XPath**.
![\[Screenshot showing the context menu in browser developer tools with various options including "Copy XPath" for extracting the XPath of a selected HTML element.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/xpath-4.png)
1. Then, open a text editor of your choice and paste the XPath you copied. The format of the XPath will look like this: `//tagname[@Attribute='Value']`.
Input the relevant XPaths you've copied in the **Authentication** section when you configure Amazon Q Web Crawler connector.
------
# Connecting Amazon Q Business to Web Crawler using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Web Crawler using the AWS Management Console.
**Note**
Before you begin adding your data source, make sure you've created an Amazon Q Business application, and added an index and retriever to it.
**Connecting Amazon Q to Web Crawler**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Web Crawler** data source to your Amazon Q application.
1. Then, on the **Web Crawler** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source** choose from the following options:
+ **Source URLs** – Add up to 10 seed/starting point URLs of the websites you want to crawl. You can also include website subdomains.
+ **Source sitemaps** – Add up to 3 sitemap URLs of the websites you want to crawl.
+ **Source URLs file** – Add up to 100 seed/starting point URLs listed in a text file in Amazon S3. Each URL should be on a separate line in the text file.
+ **Source sitemaps file** – Add up to 3 sitemap XML files stored in Amazon S3. You can also zip the XML files.
**Note**
If you choose to use a text file that includes a list of up to 100 seed URLs or to use a sitemap XML file, you specify the path to the Amazon S3 bucket where your file is stored.
You can also combine multiple sitemap XML files into a .zip file. Otherwise, you can manually enter up to 10 seed or starting point URLs, and up to three sitemap URLs.
**Note**
If you want to crawl a sitemap, check that the base or root URL is the same as the URLs listed on your sitemap page. For example, if your sitemap URL is *https://example.com/sitemap-page.html*, the URLs listed on this sitemap page should also use the base URL "https://example.com/".
**Note**
If you want to later edit your data source to change your seed URLs with authentication to sitemaps, you must create a new data source.
Amazon Q configures the data source using the seed URLs endpoint information in the Secrets Manager secret for authentication. Therefore, Amazon Q can't reconfigure the data source when changing to sitemaps.
1. In **Authentication**, choose the type of authentication you want to use and enter the following information in your AWS Secrets Manager secret:
+ **No authentication** – Choose to crawl a public website without any authentication.
+ **Basic authentication** – Enter a name for the secret, and the username and password you use to access the website you want to crawl.
+ **NTLM/Kerberos authentication** – Enter a name for the secret, and the username and password you use to access the website you want to crawl. NTLM authentication protocol includes password hashing, and Kerberos authentication protocol includes password encryption.
+ **Form authentication** – Enter a name for the secret, and the username and password you use to access the website you want to crawl. Also add the following values:
+ **User name field Xpath** – Enter the XPath for your user name field. For example, `//input[@id='username']`.
+ **Password field Xpath** – Enter the XPath for your password field. For example, `//input[@id='password']`.
+ **User name button Xpath – *Optional*** – Provide the XPath for the button associated with the username input field, typically found on a login page. For example, `//button[@id='login-submit']`. This XPath helps the automation script identify and interact with the button to proceed with the login process. You can find this XPath using your browser’s developer tools.
+ **Password button Xpath** – Provide the XPath for the button associated with the password input field, typically used to submit the login form. For example, `//button[@id='login-submit']`. This XPath is essential for automating the interaction with the button after the password has been entered. You can find this XPath using your browser’s developer tools.
**Note**
You can find the XPaths (XML Path Language) of elements using your web browser's developer tools. XPaths usually follow this format: `//tagname[@Attribute='Value']`. To learn how to retrieve XPaths, see [Retrieving XPaths (XML Path Language) for Web Crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/webcrawler-retrieving-credentials.html).
+ **SAML authentication** – Enter a name for the secret, and the username and password you use to access the website you want to crawl. Also add the following values:
+ **User name field Xpath** – Enter the XPath for your user name field. For example, `//input[@id='username']`.
+ **Password field Xpath** – Enter the XPath for your password field. For example, `//input[@id='password']`.
+ **User name button Xpath – *Optional*** – Provide the XPath for the button associated with the username input field, typically found on a login page. For example, `//button[@id='login-submit']`. This XPath helps the automation script identify and interact with the button to proceed with the login process. You can find this XPath using your browser’s developer tools.
+ **Password button Xpath** – Provide the XPath for the button associated with the password input field, typically used to submit the login form. For example, `//button[@id='login-submit']`. This XPath is essential for automating the interaction with the button after the password has been entered. You can find this XPath using your browser’s developer tools.
**Note**
You can find the XPaths (XML Path Language) of elements using your web browser's developer tools. XPaths usually follow this format: `//tagname[@Attribute='Value']`. To learn how to retrieve XPaths, see [Retrieving XPaths (XML Path Language) for Web Crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/webcrawler-retrieving-credentials.html).
1. **Web proxy – *optional*** – Enter the host name and the port number of the proxy server that you want to use to connect to internal websites. For example, the host name of *https://a.example.com/page1.html* is "a.example.com" and the port number is 443, the standard port for HTTPS. If web proxy credentials are required to connect to a website host, you can create an AWS Secrets Manager secret that stores the following credentials: the username and password required for the web proxy to log into the host URL.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/webcrawler-connector.html#webcrawler-iam).
1. In **Sync scope**, enter the following information:
1. **Sync domain range** – Choose whether to sync website domains with subdomains only, or also crawl other domains that the webpages link to (**Sync everything**). By default, Amazon Q only syncs the domains of the websites that you want to crawl.
1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB.
1. In **Additional configuration – *optional*** – Configure the following settings:
+ **Scope settings**, choose from the following:
+ **Crawl depth** – The depth, or number, of levels from the seed level to crawl. For example, the seed URL page is depth 0 and any hyperlinks on this page that are also crawled are depth 1.
+ **Maximum links per page** – The maximum number of URLs on a single webpage to crawl.
+ **Maximum throttling** – The maximum number of URLs crawled per website host per minute.
+ **Include files that web pages link to** – Select this option to allow Amazon Q Business to crawl and index files that are linked from webpages.
+ **Crawl URL patterns** – Add regular expression patterns to specify which URLs should be included or excluded during the crawling process. This allows you to control which pages on a website are crawled and which hyperlinks on those pages are indexed.
+ **URL pattern to index** – Add regular expression patterns to define which URLs or files should be included or excluded from indexing. This helps you focus the indexing process on specific URLs or files, ensuring that only the desired content is indexed.
1. **Multi-media content configuration – optional** – To enable content extraction from embedded images and visuals in documents, choose **Visual content in documents**.
To extract audio transcriptions and video content, enable processing for the following file types:
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Web Crawler using APIs
Using the API
To connect Amazon Q Business to Web Crawler using the Amazon Q API, call `CreateDataSource`. Use this API to:
+ provide a name and tags for your data source
+ an Amazon Resource Name (ARN) of an IAM role with permission to access the data source and required resources
+ a sync schedule for Amazon Q to check the documents in your data source
+ a Amazon VPC configuration
For more information on available parameters, see [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) in the [Amazon Q API reference](https://docs.aws.amazon.com/amazonq/latest/api-reference/Welcome.html).
Provide the seed or starting point URLs, or the sitemap URLs, as part of the connection configuration or repository endpoint details. Also specify the website authentication credentials and authentication type if your websites require authentication, and other necessary configurations.
**Topics**
+ [
## Web Crawler configuration properties
](#web-crawler-configuration-keys)
+ [
## Web Crawler JSON schema
](#web-crawler-api-json)
+ [
## Web Crawler JSON schema example
](#web-crawler-api-json-example)
## Web Crawler configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `type` | The type of data source. | `string` The only allowed values are [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-api.html) | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-api.html) | Yes |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has the sub-property `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. This is a sub-property for the `connectionConfiguration`. | `object` This property has the following sub-properties [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-api.html) | Yes |
| `authentication` | The authentication type if your websites require the same authentication. This is a sub-property for the `repositoryEndpointMetadata`. | `string` Depending on your connection type, the allowed values are `NoAuthentication`, `BasicAuth`, `NTLM_Kerberos`, `Form`, `SAML`. | Yes |
| `seedUrlConnections` | The list of seed or starting point URLs for the websites that you want to crawl. You can list up to 100 seed URLs. This is a sub-property for the `repositoryEndpointMetadata`. | `array` This is an array of `seedUrl`s. Use the pattern: [`https://.*`]. | No |
| `seedUrl` | The seed or starting point URL for the websites that you want to crawl. This is a sub-property for the `seedUrlConnections`. | `string` Use the pattern: [`https://.*`]. | Yes |
| `s3SeedUrl` | The S3 path to the text file that stores the list of seed or starting point URLs. This is a sub-property for the `repositoryEndpointMetadata`. | `string` Use the pattern *`s3://bucket-name/directory/` *. Each URL in the text file must be formatted on a separate line. You can list up to 100 seed URLs in a file. | No |
| `siteMapUrls` | The list of sitemap URLs for the websites that you want to crawl. This is a sub-property for the `repositoryEndpointMetadata`. | `array` This is an array of `siteMapUrls`. You can list up to three sitemap URLs. Use the pattern: [`https://.*`]. | No |
| `s3SiteMapUrl` | The S3 path to the sitemap XML files. This is a sub-property for the `repositoryEndpointMetadata`. | `string` Use the pattern, *s3://bucket-name/directory/*. You can list up to three sitemap XML files. You can club together multiple sitemap files into a .zip file and store the .zip file in your Amazon S3 bucket. | No |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-api.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-api.html) | A list of objects that map the attributes or field names of your webpages and attachments to Amazon Q index field names. | `object` These properties has the following sub-properties [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-api.html) | No |
| `indexFieldName` | The name of the index field. This is a sub-property for `webPage` and `attachments`. | `string` | Yes |
| `indexFieldType` | The type of the index field. This is a sub-property for `webPage` and `attachments`. | `string` The only allowed value are [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-api.html) | Yes |
| `dataSourceFieldName` | The field name of the data source. This is a sub-property for `webPage` and `attachments`. | `string` | Yes |
| `dateFieldFormat` | The field date of the data source. This is a sub-property for `webPage` and `attachments`. | `string` Use the pattern `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object`This property has the following sub-properties that are not required [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-api.html) | Yes |
| `rateLimit` | The maximum number of URLs crawled per website host per minute. This is a sub-property of `additionalProperties`. | `string` The default value is `300` | Yes |
| `maxFileSize` | The maximum size (in MB) of a webpage or attachment to crawl. This is a sub-property of `additionalProperties`. | `string` The default value is `50` | Yes |
| `crawlDepth` | The number of levels from the seed URL to crawl. This is a sub-property of `additionalProperties`. | `string` The seed URL page is depth `1` and any hyperlinks on this page that are also crawled are depth `2`. The default value is `2`. | Yes |
| `maxLinksPerUrl` | The maximum number of URLs on a webpage to include when crawling a website. This number is per webpage. As a website's webpages are crawled, any URLs that the webpages link to also are crawled. URLs on a webpage are crawled in order of appearance. This is a sub-property of `additionalProperties`. | `string` The default value is `100`. | Yes |
| `honorRobots` | `true` to respect the robots.txt directives of the websites that you want to crawl. These directives control how Amazon Q Web Crawler crawls the websites, and whether Amazon Q can crawl only specific content or not crawl any content. This is a sub-property of `additionalProperties`. The `honorRobots` feature is currently only available if you use the API. | `boolean` | Yes |
| `crawlSubDomain` | `true` to crawl the website domains with subdomains only. This is a sub-property of `additionalProperties`. | `boolean` If the seed URL is "abc.example.com", then "a.abc.example.com" and "b.abc.example.com" are also crawled. If you don't set `crawlSubDomain` or `crawlAllDomain` to `true`, then Amazon Q only crawls the domains of the websites that you want to crawl. | Yes |
| `crawlAllDomain` | Crawl the website domains with subdomains and other domains the web pages link to. This is a sub-property of `additionalProperties`. | `boolean` If you don't set `crawlSubDomain` or `crawlAllDomain` to `true`, then Amazon Q only crawls the domains of the websites that you want to crawl. | Yes |
| `crawlAttachments` | `true` to crawl files that the webpages link to. This is a sub-property of `additionalProperties`. | `boolean` | Yes |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. This is a sub-property of `additionalProperties`. | `string` The default value is `50`. The maximum file size should be greater than `0` and less than or equal to `50`. | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-api.html) | These are sub-properties of `additionalProperties`. A list of regular expression patterns to *include* crawling certain URLs and indexing any hyperlinks on these URL webpages. URLs that match the patterns are included in the index. URLs that don't match the patterns are excluded from the index. If a URL matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the URL and website's webpages aren't included in the index. | `array`(`string`) | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-api.html) | These are sub-properties of `additionalProperties`. A list of regular expression patterns to *exclude* crawling certain URLs and indexing any hyperlinks on these URL webpages. URLs that match the patterns are excluded from the index. URLs that don't match the patterns are included in the index. If a URL matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the URL/website's webpages aren't included in the index. | `array`(`string`) | No |
| `inclusionFileIndexPatterns` | This is a sub-property of `additionalProperties`. A list of regular expression patterns to *include* certain web page files. Files that match the patterns are included in the index. Files that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. | `array`(`string`) | No |
| `exclusionFileIndexPatterns` | This is a sub-property of `additionalProperties`. A list of regular expression patterns to *exclude* certain webpage files. Files that match the patterns are excluded from the index. Files that don't match the patterns are included in the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. | `array`(`string`) | No |
| `proxy` | This is a sub-property of `additionalProperties`. Configuration information required to connect to your internal websites through a web proxy. | `object` | No |
| `host` | This is a sub-property of `proxy`. The host name of the proxy server that you want to use to connect to internal websites.For example, the host name of *https://a.example.com/page1.html * is `a.example.com`. | `string` | No |
| port | This is a sub-property of `proxy`. The port number of the proxy server that you want to use to connect to internal websites.For example, the port 443 would be `443`. | `string` | No |
| `secretArn` | This is a sub-property of `proxy`. If web proxy credentials are required to connect to a website host, you can create an AWS Secrets Manager secret that stores the credentials. Provide the Amazon Resource Name (ARN) of the secret. | `string` The minimum length is 20and the maximum length is 2,048 characters The JSON structure for this is {
"userName": string,
"password": string
} | No |
| secretArn | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that's used if your websites require authentication to access the websites. You store the authentication credentials for the website in the secret that contains JSON key-value pairs. If you use basic, or NTLM/Kerberos, enter the username and password. The JSON keys in the secret must be `userName` and `password`. NTLM authentication protocol includes password hashing, and Kerberos authentication protocol includes password encryption. If you use SAML or form authentication, enter the username and password, XPath for the username field (and username button if using SAML), XPaths for the password field and button, and the login page URL. The JSON keys in the secret must be `userName`, `password`, `userNameFieldXpath`, `userNameButtonXpath`, `passwordFieldXpath`, `passwordButtonXpath`, and `loginPageUrl`. You can find the XPaths (XML Path Language) of elements using your web browser's developer tools. XPaths usually follow this format: `//tagname[@Attribute='Value']`. Amazon Q also checks if the endpoint information (seed URLs) included in the secret is the same the endpoint information specified in your data source endpoint configuration details. | If you use `seedUrlConnections` or `s3SeedUrl` as the connection type, you can choose from all authentication values (`NoAuthentication`, `BasicAuth`, `NTLM_Kerberos`, `Form`, `SAML`) depending on the use case. If you use `siteMapUrls` or `s3SiteMapUrl` as connection type, the `authentication` should be `NoAuthentication`. You must use the following JSON structure for your `authentication` values. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-api.html) | No |
| version | The version of this template that's currently supported. | `string` The default value is `1.0.0`. | No |
| implicitWaitDuration | Specifies how long the connector will wait, in seconds, before crawling a webpage. | Range: 0-10 eg. "implicitWaitDuration": "5" | |
## Web Crawler JSON schema
The following is the Web Crawler JSON schema:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["WEBCRAWLERV2", "WEBCRAWLER"]
},
"syncMode": {
"type": "string",
"enum": ["FORCED_FULL_CRAWL", "FULL_CRAWL"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"siteMapUrls": {
"type": "array",
"items": {
"type": "string",
"pattern": "https://.*"
}
},
"s3SeedUrl": {
"type": ["string", "null"],
"pattern": "s3:.*"
},
"s3SiteMapUrl": {
"type": ["string", "null"],
"pattern": "s3:.*"
},
"seedUrlConnections": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"seedUrl": {
"type": "string",
"pattern": "https://.*"
}
},
"required": ["seedUrl"]
}
]
},
"authentication": {
"type": "string",
"enum": [
"NoAuthentication",
"BasicAuth",
"NTLM_Kerberos",
"Form",
"SAML"
]
}
}
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"webPage": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"rateLimit": {
"type": "string",
"default": "300"
},
"maxFileSize": {
"type": "string",
"default": "50"
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"crawlDepth": {
"type": "string",
"default": "2"
},
"maxLinksPerUrl": {
"type": "string",
"default": "100"
},
"crawlSubDomain": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"crawlAllDomain": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"honorRobots": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"crawlAttachments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"inclusionURLCrawlPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionURLCrawlPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionURLIndexPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionURLIndexPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileIndexPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileIndexPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"proxy": {
"type": "object",
"properties": {
"host": {
"type": "string"
},
"port": {
"type": "string"
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
}
}
},
"implicitWaitDuration": {
"type":"object",
"properties": {
"innerNumber" : {
"type": "number",
"minimum": 0,
"maximum": 10
}
}
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": [
"rateLimit",
"maxFileSize",
"crawlDepth",
"crawlSubDomain",
"crawlAllDomain",
"maxLinksPerUrl",
"honorRobots"
]
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"type",
"syncMode",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
## Web Crawler JSON schema example
The following is the Web Crawler JSON schema example:
```
{
"type": "WEBCRAWLERV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:0123456789012:secret",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"siteMapUrls": ["https://example.com/sitemap.xml"],
"s3SeedUrl": "s3://bucket/seed-url",
"s3SiteMapUrl": "s3://bucket/sitemap-url",
"seedUrlConnections": [
{
"seedUrl": "https://example.com"
}
],
"authentication": "NoAuthentication"
}
},
"repositoryConfigurations": {
"webPage": {
"fieldMappings": [
{
"indexFieldName": "title",
"indexFieldType": "STRING",
"dataSourceFieldName": "page_title",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_title",
"indexFieldType": "STRING",
"dataSourceFieldName": "attachment_name",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"rateLimit": "300",
"maxFileSize": "50",
"crawlDepth": "2",
"maxLinksPerUrl": "100",
"crawlSubDomain": "true",
"crawlAllDomain": "true",
"honorRobots": "true"
}
}
```
# Connecting Amazon Q Business to Web Crawler using AWS CloudFormation
Using the CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
**Topics**
+ [
## Web Crawler configuration properties
](#web-crawler-configuration-keys)
+ [
## Web Crawler JSON schema for using the configuration property with AWS CloudFormation
](#web-crawler-cfn-json)
+ [
## Web Crawler YAML schema for using the configuration property with AWS CloudFormation
](#web-crawler-cfn-yaml)
## Web Crawler configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `type` | The type of data source. | `string` The only allowed values are [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-cfn.html) | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-cfn.html) | Yes |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has the sub-property `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. This is a sub-property for the `connectionConfiguration`. | `object` This property has the following sub-properties [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-cfn.html) | Yes |
| `authentication` | The authentication type if your websites require the same authentication. This is a sub-property for the `repositoryEndpointMetadata`. | `string` Depending on your connection type, the allowed values are `NoAuthentication`, `BasicAuth`, `NTLM_Kerberos`, `Form`, `SAML`. | Yes |
| `seedUrlConnections` | The list of seed or starting point URLs for the websites that you want to crawl. You can list up to 100 seed URLs. This is a sub-property for the `repositoryEndpointMetadata`. | `array` This is an array of `seedUrl`s. Use the pattern: [`https://.*`]. | No |
| `seedUrl` | The seed or starting point URL for the websites that you want to crawl. This is a sub-property for the `seedUrlConnections`. | `string` Use the pattern: [`https://.*`]. | Yes |
| `s3SeedUrl` | The S3 path to the text file that stores the list of seed or starting point URLs. This is a sub-property for the `repositoryEndpointMetadata`. | `string` Use the pattern *`s3://bucket-name/directory/` *. Each URL in the text file must be formatted on a separate line. You can list up to 100 seed URLs in a file. | No |
| `siteMapUrls` | The list of sitemap URLs for the websites that you want to crawl. This is a sub-property for the `repositoryEndpointMetadata`. | `array` This is an array of `siteMapUrls`. You can list up to three sitemap URLs. Use the pattern: [`https://.*`]. | No |
| `s3SiteMapUrl` | The S3 path to the sitemap XML files. This is a sub-property for the `repositoryEndpointMetadata`. | `string` Use the pattern, *s3://bucket-name/directory/*. You can list up to three sitemap XML files. You can club together multiple sitemap files into a .zip file and store the .zip file in your Amazon S3 bucket. | No |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-cfn.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-cfn.html) | A list of objects that map the attributes or field names of your webpages and attachments to Amazon Q index field names. | `object` These properties has the following sub-properties [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-cfn.html) | No |
| `indexFieldName` | The name of the index field. This is a sub-property for `webPage` and `attachments`. | `string` | Yes |
| `indexFieldType` | The type of the index field. This is a sub-property for `webPage` and `attachments`. | `string` The only allowed value are [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-cfn.html) | Yes |
| `dataSourceFieldName` | The field name of the data source. This is a sub-property for `webPage` and `attachments`. | `string` | Yes |
| `dateFieldFormat` | The field date of the data source. This is a sub-property for `webPage` and `attachments`. | `string` Use the pattern `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object`This property has the following sub-properties that are not required [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-cfn.html) | Yes |
| `rateLimit` | The maximum number of URLs crawled per website host per minute. This is a sub-property of `additionalProperties`. | `string` The default value is `300` | Yes |
| `maxFileSize` | The maximum size (in MB) of a webpage or attachment to crawl. This is a sub-property of `additionalProperties`. | `string` The default value is `50` | Yes |
| `crawlDepth` | The number of levels from the seed URL to crawl. This is a sub-property of `additionalProperties`. | `string` The seed URL page is depth `1` and any hyperlinks on this page that are also crawled are depth `2`. The default value is `2`. | Yes |
| `maxLinksPerUrl` | The maximum number of URLs on a webpage to include when crawling a website. This number is per webpage. As a website's webpages are crawled, any URLs that the webpages link to also are crawled. URLs on a webpage are crawled in order of appearance. This is a sub-property of `additionalProperties`. | `string` The default value is `100`. | Yes |
| `honorRobots` | `true` to respect the robots.txt directives of the websites that you want to crawl. These directives control how Amazon Q Web Crawler crawls the websites, and whether Amazon Q can crawl only specific content or not crawl any content. This is a sub-property of `additionalProperties`. The `honorRobots` feature is currently only available if you use the API. | `boolean` | Yes |
| `crawlSubDomain` | `true` to crawl the website domains with subdomains only. This is a sub-property of `additionalProperties`. | `boolean` If the seed URL is "abc.example.com", then "a.abc.example.com" and "b.abc.example.com" are also crawled. If you don't set `crawlSubDomain` or `crawlAllDomain` to `true`, then Amazon Q only crawls the domains of the websites that you want to crawl. | Yes |
| `crawlAllDomain` | Crawl the website domains with subdomains and other domains the web pages link to. This is a sub-property of `additionalProperties`. | `boolean` If you don't set `crawlSubDomain` or `crawlAllDomain` to `true`, then Amazon Q only crawls the domains of the websites that you want to crawl. | Yes |
| `crawlAttachments` | `true` to crawl files that the webpages link to. This is a sub-property of `additionalProperties`. | `boolean` | Yes |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. This is a sub-property of `additionalProperties`. | `string` The default value is `50`. The maximum file size should be greater than `0` and less than or equal to `50`. | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-cfn.html) | These are sub-properties of `additionalProperties`. A list of regular expression patterns to *include* crawling certain URLs and indexing any hyperlinks on these URL webpages. URLs that match the patterns are included in the index. URLs that don't match the patterns are excluded from the index. If a URL matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the URL and website's webpages aren't included in the index. | `array`(`string`) | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-cfn.html) | These are sub-properties of `additionalProperties`. A list of regular expression patterns to *exclude* crawling certain URLs and indexing any hyperlinks on these URL webpages. URLs that match the patterns are excluded from the index. URLs that don't match the patterns are included in the index. If a URL matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the URL/website's webpages aren't included in the index. | `array`(`string`) | No |
| `inclusionFileIndexPatterns` | This is a sub-property of `additionalProperties`. A list of regular expression patterns to *include* certain web page files. Files that match the patterns are included in the index. Files that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. | `array`(`string`) | No |
| `exclusionFileIndexPatterns` | This is a sub-property of `additionalProperties`. A list of regular expression patterns to *exclude* certain webpage files. Files that match the patterns are excluded from the index. Files that don't match the patterns are included in the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. | `array`(`string`) | No |
| `proxy` | This is a sub-property of `additionalProperties`. Configuration information required to connect to your internal websites through a web proxy. | `object` | No |
| `host` | This is a sub-property of `proxy`. The host name of the proxy server that you want to use to connect to internal websites.For example, the host name of *https://a.example.com/page1.html * is `a.example.com`. | `string` | No |
| port | This is a sub-property of `proxy`. The port number of the proxy server that you want to use to connect to internal websites.For example, the port 443 would be `443`. | `string` | No |
| `secretArn` | This is a sub-property of `proxy`. If web proxy credentials are required to connect to a website host, you can create an AWS Secrets Manager secret that stores the credentials. Provide the Amazon Resource Name (ARN) of the secret. | `string` The minimum length is 20and the maximum length is 2,048 characters The JSON structure for this is {
"userName": string,
"password": string
} | No |
| secretArn | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that's used if your websites require authentication to access the websites. You store the authentication credentials for the website in the secret that contains JSON key-value pairs. If you use basic, or NTLM/Kerberos, enter the username and password. The JSON keys in the secret must be `userName` and `password`. NTLM authentication protocol includes password hashing, and Kerberos authentication protocol includes password encryption. If you use SAML or form authentication, enter the username and password, XPath for the username field (and username button if using SAML), XPaths for the password field and button, and the login page URL. The JSON keys in the secret must be `userName`, `password`, `userNameFieldXpath`, `userNameButtonXpath`, `passwordFieldXpath`, `passwordButtonXpath`, and `loginPageUrl`. You can find the XPaths (XML Path Language) of elements using your web browser's developer tools. XPaths usually follow this format: `//tagname[@Attribute='Value']`. Amazon Q also checks if the endpoint information (seed URLs) included in the secret is the same the endpoint information specified in your data source endpoint configuration details. | If you use `seedUrlConnections` or `s3SeedUrl` as the connection type, you can choose from all authentication values (`NoAuthentication`, `BasicAuth`, `NTLM_Kerberos`, `Form`, `SAML`) depending on the use case. If you use `siteMapUrls` or `s3SiteMapUrl` as connection type, the `authentication` should be `NoAuthentication`. You must use the following JSON structure for your `authentication` values. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/web-crawler-cfn.html) | No |
| version | The version of this template that's currently supported. | `string` The default value is `1.0.0`. | No |
| implicitWaitDuration | Specifies how long the connector will wait, in seconds, before crawling a webpage. | Range: 0-10 eg. "implicitWaitDuration": "5" | |
## Web Crawler JSON schema for using the configuration property with AWS CloudFormation
Web Crawler JSON schema
The following is the Web Crawler JSON schema and examples for the configuration property for AWS CloudFormation.
**Topics**
+ [
### Web Crawler JSON schema for using the configuration property with AWS CloudFormation
](#web-crawler-cfn-json-schema)
+ [
### Web Crawler JSON schema example for using the configuration property with AWS CloudFormation
](#web-crawler-cfn-json-example)
### Web Crawler JSON schema for using the configuration property with AWS CloudFormation
Web Crawler JSON schema
The following is the Web Crawler JSON schema for the configuration property for CloudFormation
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["WEBCRAWLERV2"]
},
"syncMode": {
"type": "string",
"enum": ["FORCED_FULL_CRAWL", "FULL_CRAWL"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"siteMapUrls": {
"type": "array",
"items": {
"type": "string",
"pattern": "https://.*"
}
},
"s3SeedUrl": {
"type": ["string", "null"],
"pattern": "s3:.*"
},
"s3SiteMapUrl": {
"type": ["string", "null"],
"pattern": "s3:.*"
},
"seedUrlConnections": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"seedUrl": {
"type": "string",
"pattern": "https://.*"
}
},
"required": ["seedUrl"]
}
]
},
"authentication": {
"type": "string",
"enum": [
"NoAuthentication",
"BasicAuth",
"NTLM_Kerberos",
"Form",
"SAML"
]
}
}
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"webPage": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"rateLimit": {
"type": "string",
"default": "300"
},
"maxFileSize": {
"type": "string",
"default": "50"
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"crawlDepth": {
"type": "string",
"default": "2"
},
"maxLinksPerUrl": {
"type": "string",
"default": "100"
},
"crawlSubDomain": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"crawlAllDomain": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"honorRobots": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"crawlAttachments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"inclusionURLCrawlPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionURLCrawlPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionURLIndexPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionURLIndexPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileIndexPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileIndexPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"proxy": {
"type": "object",
"properties": {
"host": {
"type": "string"
},
"port": {
"type": "string"
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
}
}
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": [
"rateLimit",
"maxFileSize",
"crawlDepth",
"crawlSubDomain",
"crawlAllDomain",
"maxLinksPerUrl",
"honorRobots"
]
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"type",
"syncMode",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
### Web Crawler JSON schema example for using the configuration property with AWS CloudFormation
Web Crawler JSON schema example
The following is the Web Crawler JSON schema example for the configuration property for CloudFormation
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "CloudFormation Web Crawler Data Source Template",
"Resources": {
"DataSourceWebCrawler": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": "app12345-1234-1234-1234-123456789012",
"IndexId": "indx1234-1234-1234-1234-123456789012",
"DisplayName": "MyWebCrawlerDataSource",
"RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role",
"Configuration": {
"type": "WEBCRAWLERV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:0123456789012:secret",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"siteMapUrls": ["https://example.com/sitemap.xml"],
"s3SeedUrl": "s3://bucket/seed-url",
"s3SiteMapUrl": "s3://bucket/sitemap-url",
"seedUrlConnections": [
{
"seedUrl": "https://example.com"
}
],
"authentication": "BasicAuth"
}
},
"repositoryConfigurations": {
"webPage": {
"fieldMappings": [
{
"indexFieldName": "title",
"indexFieldType": "STRING",
"dataSourceFieldName": "page_title",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_title",
"indexFieldType": "STRING",
"dataSourceFieldName": "attachment_name",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"rateLimit": "300",
"maxFileSize": "50",
"crawlDepth": "2",
"maxLinksPerUrl": "100",
"crawlSubDomain": "true",
"crawlAllDomain": "true",
"honorRobots": "true"
}
}
}
}
}
}
```
## Web Crawler YAML schema for using the configuration property with AWS CloudFormation
Web Crawler YAML schema
The following is the Web Crawler YAML schema and examples for the configuration property for AWS CloudFormation:
**Topics**
+ [
### Web Crawler YAML schema for using the configuration property with AWS CloudFormation
](#web-crawler-cfn-yaml-schema)
+ [
### Web Crawler YAML schema example for using the configuration property with AWS CloudFormation
](#web-crawler-cfn-yaml-example)
### Web Crawler YAML schema for using the configuration property with AWS CloudFormation
Web Crawler YAML schema
The following is the Web Crawler YAML schema for the configuration property for CloudFormation.
```
type: object
properties:
type:
type: string
enum:
- WEBCRAWLERV2
syncMode:
type: string
enum:
- FORCED_FULL_CRAWL
- FULL_CRAWL
secretArn:
type: string
minLength: 20
maxLength: 2048
connectionConfiguration:
type: object
properties:
repositoryEndpointMetadata:
type: object
properties:
siteMapUrls:
type: array
items:
type: string
pattern: https://.*
s3SeedUrl:
type:
- string
- null
pattern: s3:.*
s3SiteMapUrl:
type:
- string
- null
pattern: s3:.*
seedUrlConnections:
type: array
items:
type: object
properties:
seedUrl:
type: string
pattern: https://.*
required:
- seedUrl
authentication:
type: string
enum:
- NoAuthentication
- BasicAuth
- NTLM_Kerberos
- Form
- SAML
required:
- repositoryEndpointMetadata
repositoryConfigurations:
type: object
properties:
webPage:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: yyyy-MM-dd'T'HH:mm:ss'Z'
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
attachment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: yyyy-MM-dd'T'HH:mm:ss'Z'
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
additionalProperties:
type: object
properties:
rateLimit:
type: string
default: "300"
maxFileSize:
type: string
default: "50"
maxFileSizeInMegaBytes:
type: string
crawlDepth:
type: string
default: "2"
maxLinksPerUrl:
type: string
default: "100"
crawlSubDomain:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
default: false
crawlAllDomain:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
default: false
honorRobots:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
default: false
crawlAttachments:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
default: false
inclusionURLCrawlPatterns:
type: array
items:
type: string
exclusionURLCrawlPatterns:
type: array
items:
type: string
inclusionURLIndexPatterns:
type: array
items:
type: string
exclusionURLIndexPatterns:
type: array
items:
type: string
inclusionFileIndexPatterns:
type: array
items:
type: string
exclusionFileIndexPatterns:
type: array
items:
type: string
proxy:
type: object
properties:
host:
type: string
port:
type: string
secretArn:
type: string
minLength: 20
maxLength: 2048
enableDeletionProtection:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
default: false
deletionProtectionThreshold:
type: string
default: "15"
required:
- rateLimit
- maxFileSize
- crawlDepth
- crawlSubDomain
- crawlAllDomain
- maxLinksPerUrl
- honorRobots
version:
type: string
anyOf:
- pattern: 1.0.0
required:
- type
- syncMode
- connectionConfiguration
- repositoryConfigurations
- additionalProperties
```
### Web Crawler YAML schema example for using the configuration property with AWS CloudFormation
Web Crawler JSON schema example
The following is the Web Crawler YAML example for the Configuration property for CloudFormation:
```
AWSTemplateFormatVersion: 2010-09-09
Description: CloudFormation Web Crawler Data Source Template
Resources:
DataSourceWebCrawler:
Type: AWS::QBusiness::DataSource
Properties:
ApplicationId: app12345-1234-1234-1234-123456789012
IndexId: indx1234-1234-1234-1234-123456789012
DisplayName: MyWebCrawlerDataSource
RoleArn: arn:aws:iam::123456789012:role/qbusiness-data-source-role
Configuration:
type: WEBCRAWLERV2
syncMode: FULL_CRAWL
secretArn: arn:aws:secretsmanager:us-west-2:0123456789012:my-webcrawler-secret
connectionConfiguration:
repositoryEndpointMetadata:
siteMapUrls:
- https://example.com/sitemap.xml
s3SeedUrl: s3://bucket/seed-url
s3SiteMapUrl: s3://bucket/sitemap-url
seedUrlConnections:
- seedUrl: https://example.com
authentication: BasicAuth
repositoryConfigurations:
webPage:
fieldMappings:
- indexFieldName: title
indexFieldType: STRING
dataSourceFieldName: page_title
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
attachment:
fieldMappings:
- indexFieldName: attachment_title
indexFieldType: STRING
dataSourceFieldName: attachment_name
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
additionalProperties:
rateLimit: "300"
maxFileSize: "50"
crawlDepth: "2"
maxLinksPerUrl: "100"
crawlSubDomain: "true"
crawlAllDomain: "true"
honorRobots: "true"
```
# Web Crawler data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Web Crawler connector supports the following entities and the associated reserved and custom attributes.
**Topics**
+ [
## Web Pages
](#web-crawler-field-mappings-web-pages)
+ [
## Attachments
](#web-crawler-field-mappings-assets)
## Web Pages
| Web Crawler field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| title | \$1document\$1title | Default | String |
| htmlSize | wc\$1html\$1size | Custom | Long (numeric) |
## Attachments
| Web Crawler field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| fileName | wc\$1file\$1name | Custom | String |
| fileType | wc\$1file\$1type | Custom | String |
| fileSize | wc\$1file\$1size | Custom | Long (numeric) |
# IAM role for Amazon Q Business Web Crawler connector
IAM role
To connect Web Crawler to Amazon Q Business, you must give Amazon Q an IAM role that has the following permissions.
**If you're crawling a public website with no authentication:**
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) operations to ingest access control information from documents.
```
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
}
```
**If you're crawling a website which uses authentication:**
+ Permission to access the AWS Secrets Manager secret that contains the credentials to connect to websites or a web proxy server backed by basic authentication.
```
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
}
```
**If your Secrets Manager secret is decrypted, add permissions for a AWS KMS key to decrypt the username and password secret stored by Secrets Manager:**
```
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
}
```
**If your Amazon Q data source connector needs access to an object stored in an Amazon S3 bucket—like seed URLs or sitemaps— you must add the following permissions to your IAM role: **
**Note**
Check that the file path to the object in your Amazon S3 bucket is of the following format: *s3://BucketName/FolderName/FileName.extension*.
```
{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
}
```
**If you are using an Amazon VPC, you need to add the following VPC access permissions to your policy:**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:us-east-1:111122223333:subnet/[[subnet_ids]]",
"arn:aws:ec2:us-east-1:111122223333:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:us-east-1:111122223333:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_111122223333_application-id_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:us-east-1:111122223333:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:us-east-1:111122223333:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_111122223333_application-id_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
------
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id"
}
}
}
]
}
```
------
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Configuring a `robots.txt` file for Amazon Q Business Web Crawler
Configuring a `robots.txt` file
The `robots.txt` file is a standard used to implement the Robots Exclusion Protocol, allowing website owners to specify which parts of their site visiting web crawlers and robots can access. Amazon Q Business Web Crawler adheres to the rules set in your website’s `robots.txt` file, which determines the areas it is allowed or not allowed to visit. Amazon Q Business Web Crawler respects standard robots.txt directives like `Allow` and `Disallow`. To control how Amazon Q Business Web Crawler interacts with your website, you can simply adjust these rules in your robots.txt file.
**Topics**
+ [
## Configuring how Amazon Q Web Crawler accesses your website
](#configure-web-crawler-website-access)
+ [
## Stopping Amazon Q Web Crawler from crawling your website
](#stop-web-crawler-access)
## Configuring how Amazon Q Web Crawler accesses your website
You can control how the Amazon Q Web Crawler indexes your website using `Allow` and `Disallow` directives. You can also control which web pages are indexed and which web pages are not crawled.
**To allow Amazon Q Web Crawler to crawl all web pages except disallowed web pages, use the following directive:**
```
User-agent: amazon-QBusiness # Amazon Q Web Crawler
Disallow: /credential-pages/ # disallow access to specific pages
```
**To allow Amazon Q Web Crawler to crawl only specific web pages, use the following directive:**
```
User-agent: amazon-QBusiness # Amazon Q Web Crawler
Allow: /pages/ # allow access to specific pages
```
**To allow Amazon Q Web Crawler to crawl all website content and disallow crawling for any other robots, use the following directive:**
```
User-agent: amazon-QBusiness # Amazon Q Web Crawler
Allow: / # allow access to all pages
User-agent: * # any (other) robot
Disallow: / # disallow access to any pages
```
## Stopping Amazon Q Web Crawler from crawling your website
You can stop Amazon Q Web Crawler from indexing your website using the `Disallow` directive. You can also control which web pages are crawled and which aren't.
**To stop Amazon Q Web Crawler from crawling the website, use the following directive:**
```
User-agent: amazon-QBusiness # Amazon Q Web Crawler
Disallow: / # disallow access to any pages
```
If you have any questions or concerns about Amazon Q Web Crawler, you can reach out to the [AWS support team](https://aws.amazon.com/contact-us/?nc1=f_m).
# Connecting Asana to Amazon Q Business (Preview)
Asana (*Preview*)
**Note**
The Asana connector is in preview release and is subject to change.
Asana is a tool for organizing and assigning tasks among users. You can connect a Asana instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# Known limitations for the Amazon Q Business Asana connector (Preview)
](Asana-limitations.md)
+ [
# Asana connector overview (Preview)
](Asana-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Asana (Preview)
](Asana-prereqs.md)
+ [
# Connecting Amazon Q Business to Asana using the console (Preview)
](Asana-console.md)
+ [
# Connecting Amazon Q Business to Asana using APIs (Preview)
](Asana-api.md)
+ [
# Amazon Q Business Asana data source connector field mappings (Preview)
](Asana-field-mappings.md)
+ [
# IAM role for Amazon Q Business Asana connector (Preview)
](Asana-iam-role.md)
+ [
# Understand error codes in the Amazon Q Business Asana connector (Preview)
](Asana-error-codes.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Amazon Q Business Asana connector (Preview)
Known limitations
The Asana connector has the following known limitations:
+ Asana supports crawling on only Public Projects.
# Asana connector overview (Preview)
Overview
The following table gives an overview of the Amazon Q Business Asana connector and its supported features.
****
| Category | Feature | Support |
| --- | --- | --- |
| Security | Authentication type | Service Account and PAT |
| Authentication credentials | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/Asana-overview.html) |
| [Access Control List (ACL)](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) crawling | No. For preview, this connector only scans public Asana projects. For more information, see [ACL crawling](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/zendesk-user-management.html). |
| [Identity crawling](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler) | No |
| [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc) | Yes |
| Crawl features | Custom metadata | No |
| Entities | Yes. The following entities are supported: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/Asana-overview.html) Each instance of an entity is crawled as a single document. |
| [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings) | Yes. For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/zendesk-field-mappings.html). |
| Filters | Yes. The following filters are supported: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/Asana-overview.html) |
| [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode) | Supports full and incremental sync. |
| [Crawled as a document](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-types.html#connector-doc-crawl) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/Asana-overview.html) |
# Prerequisites for connecting Amazon Q Business to Asana (Preview)
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Asana, make sure you have:**
+ Generated an access token.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Asana authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Asana using the console (Preview)
Using the console
The following procedure outlines how to connect Amazon Q Business to Asana using the AWS Management Console.
**Connecting Amazon Q to Asana**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **asana** data source to your Amazon Q application.
1. Then, on the **Asana** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Sync scope, Workspace ID** – Enter your workspace Id.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. **Authentication** – Enter your service account token or personal access token.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **Identity crawler** – Amazon Q crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/Asana-connector.html#Asana-iam).
1. **Sync scope** –
+ In Select workspace – Select content to sync using a specific Workspace ID.
+ Select Project – Select content to sync using All or Specific Project IDs.
+ All comments – Select to include all comments.
1. **Additional configuration – optional** – Configure the following settings:
+ In Additional configuration – select from the following options
+ Project regex patterns – Choose to include or exclude specific project names using regex patterns.
+ Document deletion safeguard - optional–To safeguard your documents from deletion during a sync job, select On and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see Document deletion safeguard.
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Asana using APIs (Preview)
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
## JSON schema
The following is the Asana JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"authType": {
"type": "string",
"enum": [
"PAT",
"ServiceAccount"
]
}
},
"required": [
"authType"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"project": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE",
"STRING_LIST",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"task": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE",
"STRING_LIST",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE",
"STRING_LIST",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"workspaceIds": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 1
},
"projectIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 12,
"maxLength": 16
},
"maxItems": 20
},
"fieldForUserId": {
"type": "string"
},
"isCrawlAcl": {
"type": "boolean"
},
"isCrawlComments": {
"type": "boolean"
},
"inclusionProjectNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionProjectNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"enableDeletionProtection": {
"type": "boolean",
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
}
},
"enableIdentityCrawler": {
"type": "boolean"
},
"syncMode": {
"type": "string",
"enum": [
"FULL_CRAWL",
"FORCED_FULL_CRAWL"
]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"type": {
"type": "string",
"pattern": "ASANA"
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint of the data source. |
| repositoryEndpointMetadata | The endpoint information for the data source. |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/Asana-api.html) | A list of Asana objects and their metadata attributes that Amazon Q crawls and maps to Amazon Q index field names. The Asana data source field names must exist in your Asana custom metadata. |
| secretARN | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Asana. |
| additionalProperties [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/Asana-api.html) | Additional configuration options for your content in your data source. |
| fieldForUserId | Specify field to use for UserId for ACL crawling. |
| inclusionProjectNamePatterns | A list of regular expression patterns to include specific projects in your Asana data source. projects that match the patterns are included in the index. Projects that don't match the patterns are excluded from the index. If a project matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. |
| exclusionProjectNamePatterns | A list of regular expression patterns to exclude specific projects in your Asana data source. Projects that match the patterns are excluded from the index. Projects that don't match the patterns are included in the index. If a project matches both an exclusion and inclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. |
| isCrawlComments | Input true to index these types of content. |
| isCrawlACL | Input must be False as Asana does not support document crawling with ACL. |
| type | Specify ASANA as your data source type. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/Asana-api.html) |
| enableIdentityCrawler | This will always be false as Asana does not support Identity Crawling. Identity crawler is activated by default. Crawling identity information on users and groups with access to certain documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). |
| version | The version of the template that's currently supported. |
# Amazon Q Business Asana data source connector field mappings (Preview)
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application environment and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes-types.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Asana connector supports the following entities and the associated reserved and custom attributes.
**Topics**
+ [
## Projects
](#Asana-field-mappings-projects)
+ [
## Tasks
](#Asana-field-mappings-tasks)
+ [
## Comments
](#Asana-field-mappings-comments)
## Projects
Amazon Q supports crawling Asana Projects and offers the following project field mappings.
| Asana field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| projectPermaLink | \$1source\$1uri | Default | String |
| projectCreatedDate | \$1created\$1at | Default | Date |
| projectModifiedDate | \$1last\$1updated\$1at | Default | Date |
| catagory | \$1catagory | Default | String |
| isArchived | asana\$1archived | Custom | Custom |
| dueOn | asana\$1dueOn | Custom | Date |
| startOn | asana\$1startOn | Custom | String |
| isPublicProject | asana\$1isPublicProject | Custom | String |
| ownerId | asana\$1ownerId | Custom | String |
| ownerName | asana\$1ownerName | Custom | String |
| teamId | asana\$1teamId | Custom | String list |
| teamName | asana\$1teamName | Custom | String list |
| workspaceId | asana\$1workspaceId | Custom | String |
| workspaceName | asana\$1workspaceName | Custom | String |
| isOrganization | asana\$1isOrganization | Custom | String |
## Tasks
Amazon Q supports crawling Asana Tasks and offers the following project field mappings.
| Asana field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| taskPermaLink | \$1source\$1uri | Default | String |
| taskCreatedDate | \$1created\$1at | Default | Date |
| taskModifiedDate | \$1last\$1update\$1at | Default | Date |
| category | \$1category | Default | String |
| assigneeId | asana\$1assigneeId | Custom | String |
| assigneeName | asana\$1assigneeName | Custom | String |
| isCompleted | asana\$1isCompleted | Custom | String |
| dueOn | asana\$1dueOn | Custom | String |
| isSubtask | asana\$1isSubtask | Custom | String |
| topLevelTaskId | asana\$1topLevelTaskId | Custom | String |
| topLevelTaskName | asana\$1topLevelTaskName | Custom | String |
| section Id | asana\$1sectionId | Custom | String |
| sectionName | asana\$1sectionName | Custom | String |
| projectId | asana\$1projectId | Custom | String |
| projectName | asana\$1projectName | Custom | String |
| workspaceId | asana\$1workspaceId | Custom | String |
| workspaceName | asana\$1workspaceName | Custom | String |
| isOrganization | asana\$1isOrganization | Custom | String |
## Comments
Amazon Q supports crawling Asana Comments and offers the following project field mappings.
| Asana field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| commentPermaLink | \$1source\$1uri | Default | String |
| category | \$1category | Default | String |
| taskId | asana\$1taskId | Custom | String |
| taskName | asana\$1taskName | Custom | String |
| teamId | asana\$1teamId | Custom | String |
| teamName | asana\$1teamName | Custom | String |
| sectionId | asana\$1sectionId | Custom | String |
| sectionName | asana\$1sectionName | Custom | String |
| projectId | asana\$1projectId | Custom | String |
| projectName | asana\$1projectName | Custom | String |
| workspaceId | asana\$1workspaceId | Custom | String |
| workspaceName | asana\$1workspaceName | Custom | String |
| isOrganization | asana\$1isOrganization | Custom | String |
# IAM role for Amazon Q Business Asana connector (Preview)
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Understand error codes in the Amazon Q Business Asana connector (Preview)
Error Codes
The following table provides information about error codes you may see for the Asana connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| ASN-5101 | The token in your data source configuration is missing. | Enter valid token (specific to PAT or ServiceAccount) and try again. |
| ASN-5102 | The auth type in your data source configuration is invalid. | Enter valid auth type (PAT or ServiceAccount) and try again. |
| ASN-5103 | The auth type in your data source configuration is missing. | Enter valid auth type (PAT or ServiceAccount) and try again. |
| ASN-5104 | The crawl type in your data source configuration is missing. | Enter valid crawlType (ex. FULL\$1CRAWL) and try again. |
| ASN-5105 | Only String, String List, Date and Long formats are supported for the indexFieldType in all the field mappings. | Please provide the supported format only for the indexFieldType in all the fieldMappings. |
| ASN-5106 | There was an error parsing the field value. The size has exceeded the maximum allowable limit. | The maximum size permitted is 1000 for the field \$1field name\$1. Ex – field name can be token, workspaceId, projectId |
| ASN-5107 | The connection configuration in your data source configuration is missing. | Enter valid connection configuration details and try again. |
| ASN-5108 | The repository credentials in your data source configuration is missing. | Enter valid repository credentials details and try again. |
| ASN-5109 | The repository endpoint metadata in your data source configuration is missing. | Enter valid repository endpoint metadata details and try again. |
| ASN-5110 | The additional properties in your data source configuration is missing.Error message | Enter valid additional properties and try again. |
| ASN-5111 | Invalid Workspace Id. | Provide numeric value for workspace Id. |
| ASN-5112 | Invalid Project Id. | Provide numeric value for Project Id. |
| ASN-5113 | The workspaceIds field has exceeded the limit. Allowed entries are limited to 1. | Correct the number of entries and try again. |
| ASN-5114 | The projectIds field has exceeded the limit. Maximum allowed entries are 20. | Correct the number of entries and try again. |
| ASN-5115 | The regex pattern provided in \$1pattern field\$1 Patterns is invalid. | Provide valid regex pattern. |
| ASN-5116 | The workspace Id in your data source configuration is missing. | Enter a single workspace Id and try again. |
| ASN-5200 | IO Exception occurred while reading contents from Asana. | Rerun the connector once again, if the issue persists contact support. |
| ASN-5201 | Unknown exception occurred. | Rerun the connector once again, if the issue persists contact support. |
| ASN-5202 | The user details are not found. | Verify the user data using the user API curl command or in postman for the given authentication type. |
| ASN-5204 | Could not find Project(s) using the filter provided in the Asana configuration. Either Workspace(s) or Project(s) access is forbidden. | Check the Workspace and Project(s) access and provide valid inclusion and exclusion project name filter inputs. |
| ASN-5500 | Asana connection successful. | This is to convey the connection to Asana data source is successful. |
# Connecting Box to Amazon Q Business
Box
Box is a cloud storage service that offers file hosting capabilities. You can connect your Box instance to Amazon Q Business—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# Known limitations for the Box connector
](box-limitations.md)
+ [
# Box connector overview
](box-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Box
](box-prereqs.md)
+ [
# Connecting Amazon Q Business to Box using the console
](box-console.md)
+ [
# Connecting Amazon Q Business to Box using APIs
](box-api.md)
+ [
# How Amazon Q Business connector crawls Box ACLs
](box-user-management.md)
+ [
# Box data source connector field mappings
](box-field-mappings.md)
+ [
# IAM role for Box connector
](box-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Box connector
Known limitations
The Amazon Q Box connector has the following known limitations:
+ Crawling data from external folders is not supported.
+ When Access Control Lists (ACLs) are enabled, the "Sync only new or modified content" option is not available due to Box API limitations. We recommend using "Full sync" or "New, modified, or deleted content sync" modes instead, or disable ACLs if you need to use this sync mode.
# Box connector overview
Overview
The following table gives an overview of the Amazon Q Business Box connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/box-overview.html)
# Prerequisites for connecting Amazon Q Business to Box
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Box, make sure you have:**
+ A Box Enterprise or Box Enterprise Plus account.
+ Created a Box custom app in the Box Developer Console and configured it to use **Server Authentication (with JWT)**.
+ Set your **App Access Level** to **App \$1 Enterprise Access** and allowed it to **Make API calls using the as-user header**.
+ Used the admin user to add the following **Application Scopes** in your Box app:
+ Write all files and folders stored in a Box
+ Manage users
+ Manage groups
+ Manage enterprise properties
+ Generated and downloaded Public/Private key pair including a client ID, a client secret, a public key ID, private key ID, a pass phrase, and an enterprise ID to use as authentication credentials. See [Public and private keypair](https://developer.box.com/guides/authentication/jwt/jwt-setup/#public-and-private-key-pair) for more details.
+ Copied your Box enterprise ID either from your Box Developer Console settings or from your Box app. For example, *801234567*.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Box authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
**Note**
For more information on connecting Box to Amazon Q Business, see [Discover insights from Box with the Amazon Q Box connector](https://aws.amazon.com/blogs/machine-learning/discover-insights-from-box-with-the-amazon-q-box-connector/) in the *AWS Machine Learning Blog*.
# Connecting Amazon Q Business to Box using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Box using the AWS Management Console.
**Connecting Amazon Q to Box**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Box** data source to your Amazon Q application.
1. Then, on the **Box** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. **Source** – Enter your **Box enterprise ID**.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. In **Authentication** – Choose to create an **AWS Secrets Manager secret** and then enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. **Client ID** – The client ID provided by Box.
1. **Client Secret** – The client secret provided by Box.
1. **Public Key ID** – Your Box public key ID.
1. **Private Key** – The private key provided by Box.
1. **Pass Phrase** – The pass phrase you use to log into your Box account.
1. **Identity crawler** – Amazon Q crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/box-connector.html#box-iam).
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. In **Sync scope**, enter the following information:
1. **Select additional kinds of content to index** – Choose whether to include **Web links**, **Comments**, and **Tasks**.
**Note**
Box files are indexed by default.
1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB.
1. **Additional configuration – *optional*** – Configure the following settings:
+ **Regex patterns** – Regular expression patterns to include or exclude certain files. You can add up to 100 patterns.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. For **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Box using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
## Box JSON schema
The following is the Box JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"enterpriseId": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"required": [
"enterpriseId"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"file": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"STRING_LIST",
"DATE",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
},
"task": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"STRING_LIST",
"DATE",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"STRING_LIST",
"DATE",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
},
"webLink": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"STRING_LIST",
"DATE",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"type": "boolean"
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"crawlComments": {
"type": "boolean"
},
"crawlTasks": {
"type": "boolean"
},
"crawlWebLinks": {
"type": "boolean"
},
"inclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": []
},
"type": {
"type": "string",
"pattern": "BOX"
},
"enableIdentityCrawler": {
"type": "boolean"
},
"syncMode": {
"type": "string",
"enum": [
"FULL_CRAWL",
"FORCED_FULL_CRAWL",
"CHANGE_LOG"
]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type",
"enableIdentityCrawler"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | The endpoint information for the data source. |
| enterpriseId | The Box enterprise id. |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/box-api.html) | A list of objects that map the attributes or field names of your Box files, tasks, comments, and webLinks to Amazon Q index field names. |
| additionalProperties | Additional configuration options for your content in your data source. |
| maxFileSizeInMegaBytes | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. |
| isCrawlAcl | Specify true to crawl access control information from documents. Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. |
| fieldForUserId | Specify field to use for UserId for ACL crawling. |
| crawlComments | Specify true to crawl assets. |
| crawlTasks | Specify true to crawl pages. |
| crawlWebLinks | Specify true to crawl pages. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/box-api.html) | A list of regular expression patterns to include or exclude specific content from your Box data source. Content that matches the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. |
| type | The type of data source. Specify BOX as your data source type. |
| enableIdentityCrawler | Specify true to use the Amazon Q identity crawler to sync identity/principal information on users and groups with access to specific documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/box-api.html) |
| secretArn | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Box. The secret must contain a JSON structure with the following keys: {
"clientID": "client-id",
"clientSecret": "client-secret",
"publicKeyID": "public-key-id",
"privateKey": "private-key",
"passphrase": "pass-phrase"
} |
| version | The version of this template that's currently supported. |
# How Amazon Q Business connector crawls Box ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
**Roles/permissions**: The Box connector translates Box permissions into ACLs that are compatible with Amazon Q Business. There are seven primary roles with permissions:
+ Co-owner - Has full control, can change advanced folder settings
+ Editor - Has read/write access, can view, download, edit, delete, and manage sharing.
+ Viewer - Has read-only access, can preview and download
+ Uploader - Has limited write access, can only upload and see names
+ Viewer Uploader - A combination of Viewer and Uploader capabilities
+ Previewer - Has limited read access, can only preview items
+ Previewer Uploader - A combination of Previewer and Uploader capabilities
**Permission Inheritance**: Files/subfolders inherit permissions from parent folders by default. Permissions follow a "waterfall" design where individuals have access to the folder they are invited into and any subfolders beneath it. Changing permissions on subfolders will result in an error because collaboration is only changeable at the item where it was created.
**Identity Crawling**: Individual user and group synchronization is supported via email addresses. Each user gets a unique user ID, even if recreated with the same email address. Permissions are tied to user IDs, not email addresses.
Change Management: ACL changes are supported in change log mode, including collaboration invites, accepts, and role changes.
Failure handling: The connector implements a fail-close approach for API failures, with rate limiting handled through queue-based wait time with exponential backoff. Documents are skipped from ingestion rather than being made publicly accessible when permission-related issues occur.
For more information, see [Key data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/-connector-app.html#-connector-key-concepts).
# Box data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Box connector supports the following entities and the associated reserved and custom attributes.
**Topics**
+ [
## Files and folders
](#box-field-mappings-files-folders)
+ [
## Comments
](#box-field-mappings-comments)
+ [
## Tasks
](#box-field-mappings-tasks)
+ [
## Web links
](#box-field-mappings-web-links)
## Files and folders
| Box field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| bx\$1createdAt | \$1created\$1at | Default | Date |
| bx\$1modifiedAt | \$1last\$1updated\$1at | Default | Date |
| bx\$1authors | \$1authors | Default | String list |
| bx\$1uri | \$1source\$1uri | Default | String |
| bx\$1size | bx\$1file\$1size | Custom | String |
| bx\$1category | \$1category | Default | String |
## Comments
| Box field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| bx\$1createdAt | \$1created\$1at | Default | Date |
| bx\$1modifiedAt | \$1last\$1updated\$1at | Default | Date |
| bx\$1author | \$1authors | Custom | String |
| bx\$1parentFile | bx\$1comment\$1item | Custom | String |
| bx\$1category | \$1category | Default | String |
## Tasks
| Box field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| bx\$1createdAt | \$1created\$1at | Default | Date |
| bx\$1action | bx\$1task\$1action | Custom | String |
| bx\$1taskComplete | bx\$1task\$1completed | Custom | String |
| bx\$1taskItem | bx\$1task\$1item | Custom | String |
| bx\$1taskAssigned | bx\$1task\$1assigned\$1to | Custom | String |
| bx\$1author | bx\$1author | Custom | String |
| bx\$1category | \$1category | Default | String |
| bx\$1uri | \$1source\$1uri | Default | String |
## Web links
| Box field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| bx\$1createdAt | \$1created\$1at | Default | Date |
| bx\$1author | bx\$1author | Custom | String |
| bx\$1category | \$1category | Default | String |
| bx\$1uri | \$1source\$1uri | Default | String |
# IAM role for Box connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Confluence (Cloud) to Amazon Q Business
Confluence (Cloud)
Atlassian Confluence is a collaborative work-management tool designed for sharing, storing, and working on project planning, software development, and product management. You can connect Confluence (Cloud) instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# Confluence (Cloud) connector overview
](confluence-cloud-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Confluence (Cloud)
](confluence-cloud-prereqs.md)
+ [
# Setting up Confluence (Cloud) for connecting to Amazon Q Business
](confluence-cloud-credentials.md)
+ [
# Connecting Amazon Q Business to Confluence (Cloud) using the console
](confluence-cloud-console.md)
+ [
# Connecting Amazon Q Business to Confluence (Cloud) using APIs
](confluence-cloud-api.md)
+ [
# Connecting Amazon Q Business to Confluence (Cloud) using AWS CloudFormation
](confluence-cloud-cfn.md)
+ [
# How Amazon Q Business connector crawls Confluence (Cloud) ACLs
](confluence-cloud-user-management.md)
+ [
# Amazon Q Business Confluence (Cloud) data source connector field mappings
](confluence-cloud-field-mappings.md)
+ [
# IAM role for Amazon Q Confluence (Cloud) connector
](confluence-cloud-iam-role.md)
+ [
# Understand error codes in the Amazon Q Business Confluence (Cloud) connector
](confluence-cloud-error-codes.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Confluence (Cloud) connector overview
Overview
The following table contains an overview of the Amazon Q Business Confluence (Cloud) connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-cloud-overview.html)
# Prerequisites for connecting Amazon Q Business to Confluence (Cloud)
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Confluence Cloud, make sure you have:**
+ Copied your Confluence instance URL. For example: *https://example.atlassian.net*. You need your Confluence instance URL to connect to Amazon Q.
+ Configured basic authentication credentials containing a username (email ID used to log into Confluence) and password (Confluence API token) to allow Amazon Q to connect to your Confluence instance. For information about how to create a Confluence API token, see [Manage API tokens for your Atlassian account](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/#Create-an-API-token) on the Atlassian website.
+ **Optional:** Configured OAuth 2.0 credentials containing a Confluence app key, Confluence app secret, Confluence access token, and Confluence refresh token to allow Amazon Q to connect to your Confluence instance. If your access token expires, you can either use the refresh token to regenerate your access token and refresh token pair, or you can repeat the authorization process. For more information about access tokens, see [Manage OAuth access tokens](https://support.atlassian.com/confluence-cloud/docs/manage-oauth-access-tokens/) on the Atlassian website.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ If you want to have Amazon Q automatically rotate your secret, ensure that your IAM role includes the `secretsmanager:PutSecretValue` and `secretsmanager:UpdateSecret` permissions.
+ Stored your Confluence (Cloud) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
**Note**
For more information on connecting Confluence (Cloud) to Amazon Q Business, see [Index your Atlassian Confluence Cloud contents using the Amazon Q Confluence Cloud connector for Amazon Q Business](https://aws.amazon.com/blogs/machine-learning/index-your-atlassian-confluence-cloud-contents-using-the-amazon-q-confluence-cloud-connector-for-amazon-q-business/) in the *AWS Machine Learning Blog*.
# Setting up Confluence (Cloud) for connecting to Amazon Q Business
Setting up Confluence (Cloud)
Before you connect Confluence (Cloud) to Amazon Q Business, you need to create and retrieve the Confluence (Cloud) credentials you will use to connect Confluence (Cloud) to Amazon Q. You will also need to add any permissions needed by Confluence (Cloud) to connect to Amazon Q.
The following sections give you an overview of how to configure Confluence (Cloud) to connect to Amazon Q using either basic authentication or OAuth 2.0 authentication.
**Topics**
+ [
# Basic authentication
](confluence-cloud-credentials-basic.md)
+ [
# OAuth 2.0 authentication
](confluence-cloud-credentials-oauth.md)
+ [
# How Amazon Q works with Confluence (Cloud) access and refresh tokens
](confluence-cloud-credentials-notes.md)
+ [
# Checking Confluence (Cloud) connectivity
](confluence-cloud-connection-check.md)
# Basic authentication
You can connect Amazon Q to Confluence (Cloud) using basic authentication credentials. The following procedure gives you an overview of how to configure Confluence (Cloud) to connect to Amazon Q using basic authentication.
**Configuring Confluence (Cloud) basic authentication for Amazon Q**
1. Log in to your account from the [Confluence (Cloud)](https://confluence.atlassian.com/). Note the username you logged in with. You will need this later to connect to Amazon Q.
1. From your Confluence (Cloud) home page, note your Confluence (Cloud) URL from your Confluence browser URL. For example: *https://example.atlassian.net*. You will need this later to connect to Amazon Q.
1. Then, go to [Security]( https://id.atlassian.com/manage-profile/security/api-tokens.) page in Confluence (Cloud).
1. From the **API tokens** page, select **Create API token**.
![\[Screenshot of the Atlassian account settings page showing where to access API tokens.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-1.png)
1. In the **Create an API token** dialog box that opens, for **Label**, add a name for your API token. Then, select **Create**.
![\[Screenshot of the "Create an API token" dialog box where users enter a label for their API token.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-2.png)
1. From the **Your new API token** dialog box, copy the API token and save it in a text editor of your choice. You can't retrieve the API token once you close the dialog box.
![\[Screenshot of the "Your new API token" dialog box displaying the generated API token that needs to be copied and saved.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-3.png)
1. Select **Close**.
You now have the username, Confluence (Cloud) URL, and Confluence (Cloud) API token you need to connect to Amazon Q with basic authentication.
For more information, see [Manage API tokens for your Atlassian account](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) in Atlassian Support.
## Atlassian Admin Authentication
To ensure Amazon Q can access all user and group information from your Confluence (Cloud) instance, you must provide Atlassian admin credentials. These credentials allow Amazon Q to sync user information regardless of individual email visibility settings.
### Get your Atlassian admin credentials
1. Sign in to the [Atlassian admin portal](https://admin.atlassian.com/) with administrator permissions.
1. Open the Administration app for your organization. The URL should look like: `https://admin.atlassian.com/o/{ORGANIZATION-UUID}/overview`
1. Choose **Settings**, then choose **API Keys**.
1. Choose **Create API key**.
1. Select all available scopes for the API key.
Note that the Confluence APIs that fetch user and group information require full scope access.
1. Copy and save both the **Organization ID** and **API Key**. Note that API keys expire. Monitor the expiration date and update your data source credentials before the key expires.
### Get your Directory ID
1. Use the Atlassian Admin Workspace API to get your Directory ID. Run the following command:
```
curl --request POST \
--url 'https://api.atlassian.com/admin/v2/orgs/{ORGANIZATION-ID}/workspaces' \
--header 'Authorization: Bearer {API-KEY}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
```
1. In the API response, find the workspace entry that matches your Confluence Cloud instance. Look for `"type": "Confluence"`. Verify the workspace name matches your instance and then copy the directory value from the attributes section. If your instance isn't listed, use the pagination cursor in the `links.next` field to view additional pages.
```
curl --request POST \
--url 'https://api.atlassian.com/admin/v2/orgs/{ORGANIZATION-ID}/workspaces' \
--header 'Authorization: Bearer {API-KEY}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"cursor": "{NEXT-PAGE-TOKEN}"}'
```
### Update your Confluence data source
When creating or updating your Confluence Cloud data source, provide these three values in your AWS Secrets Manager secret:
1. Admin API Key
1. Organization ID
1. Directory ID
For more information about Atlassian admin API scopes, see [Atlassian API scopes documentation](https://developer.atlassian.com/cloud/admin/scopes/).
For API details, see [Atlassian Admin Workspace API reference](https://developer.atlassian.com/cloud/admin/organization/rest/api-group-workspaces/#api-group-workspaces).
# OAuth 2.0 authentication
You can connect Amazon Q to Confluence (Cloud) using OAuth 2.0 authentication credentials. The following procedures give you an overview of how to configure Confluence (Cloud) to connect to Amazon Q using OAuth 2.0 authentication.
**Topics**
+ [
## Step 1: Retrieving username and Confluence (Cloud) URL
](#confluence-cloud-credentials-url)
+ [
## Step 2: Configuring an OAuth 2.0 app integration
](#confluence-cloud-credentials-oauth-app)
+ [
## Step 3: Retrieving Confluence (Cloud) client ID and client Secret
](#confluence-cloud-credentials-id-secret)
+ [
## Step 4: Generating an Confluence (Cloud) access token
](#confluence-cloud-credentials-access)
+ [
## Step 5: Generating a Confluence (Cloud) refresh token
](#confluence-cloud-credentials-refresh)
+ [
## Step 6: Generating a new Confluence (Cloud) access token using a refresh token
](#confluence-cloud-credentials-refresh-access)
## Step 1: Retrieving username and Confluence (Cloud) URL
To connect Confluence (Cloud) to Amazon Q, you need your Confluence (Cloud) username and your Confluence (Cloud) URL. The following procedure shows you how to retrieve these.
**Retrieving username and Confluence (Cloud) URL**
1. Log in to your account from the [Confluence (Cloud)](https://confluence.atlassian.com/). Note the username you logged in with. You will need this later to connect to Amazon Q.
1. From your Confluence (Cloud) home page, note your Confluence (Cloud) URL from your Confluence browser URL. For example: *https://example.atlassian.net*. You will need this later to both configure your OAuth 2.0 token and connect to Amazon Q.
## Step 2: Configuring an OAuth 2.0 app integration
To connect Confluence (Cloud) to Amazon Q using OAuth 2.0 authentication, you need to create a Confluence (Cloud) OAuth 2.0 app with the necessary permissions. The following procedure shows you how to create this.
**Configuring an OAuth 2.0 app integration**
1. Log in to your account from the [Atlassian Developer page](https://developer.atlassian.com/).
1. Select the profile icon from the top-right corner. Then, from the dropdown menu that opens, select **Developer Console**.
![\[Screenshot of the Atlassian Developer Console showing the "Create" button and options for creating a new integration.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-4.png)
1. From the **Welcome** page, select **Create** and then select **OAuth 2.0 integration**.
![\[Screenshot of the Atlassian Developer Console welcome page showing the "Create" dropdown menu with the "OAuth 2.0 integration" option highlighted.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-5.png)
1. On the **Create a new OAuth 2.0 (3LO) integration** page, for **Name**, enter a name for the OAuth 2.0 application you are creating. Then, select the **I agree to be bound by Atlassian's developer terms** checkbox, and select **Create**.
![\[Screenshot of the "Create a new OAuth 2.0 (3LO) integration" page where users enter a name for the OAuth application and agree to the Atlassian developer terms.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-6.png)
The console will display a summary page outlining the details of the OAuth 2.0 app created.
![\[Screenshot of the OAuth 2.0 app summary page showing details of the created application including name, ID, and other configuration information.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-7.png)
1. From the left navigation menu, choose **Authorization**.
1. From the **Authorization** page, choose **Add** to add **OAuth 2.0 (3LO)** to your app.
![\[Screenshot of the OAuth 2.0 app's Authorization page showing the "Add callback URL" button that users need to click to configure the callback URL for the OAuth flow.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-8.png)
1. On the **OAuth 2.0 authorization code grants (3LO) for apps**, enter the Confluence (Cloud) URL you copied as the **Callback URL** and then choose **Save changes**.
![\[Screenshot of the "OAuth 2.0 authorization code grants (3LO) for apps" section showing the Callback URL field where users enter the Confluence URL for the OAuth redirect.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-9.png)
1. From the **Authorization URL generator** section that appears, choose **Add APIs** to add APIs to your app. This will redirect you to the **Permissions** page.
1. On the **Permissions** page, for **Scopes**, navigate to **User Identity API**. Select **Add**, and then select **Configure**.
![\[Screenshot of the Permissions page showing the "User Identity API" option that needs to be selected to configure user identity permissions for the OAuth app.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-10.png)
1. On the **User Identity API** page, choose **Edit Scopes**, and the add the following `read` scopes:
+ **`read:me`** – View active user profile
+ **`read:account`** – View user profiles
![\[Screenshot of the User Identity API permissions page showing the available scopes that can be selected for the OAuth application, with read scopes highlighted.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-12.png)
Then, select **Save**.
1. Return to the **Permissions** page. From **Scopes**, navigate to **Confluence API**. Select **Add**, and the select **Configure**.
![\[Screenshot of the Permissions page showing the Confluence API option that needs to be selected to configure API permissions for accessing Confluence content.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-11.png)
1. Navigate to the **Granular scopes** page.
![\[Screenshot of the Confluence API Granular scopes page showing the available API permission scopes that can be configured for the OAuth application.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-14.png)
Then, choose **Edit Scopes**, and the add the following `read` scopes:
+ **`read:content:confluence`** – View detailed contents
+ **`read:content-details:confluence`** – View content details
+ **`read:space-details:confluence`** – View space details
+ **`read:audit-log:confluence`** – View audit records
+ **`read:page:confluence`** – View pages
+ **`read:attachment:confluence`** – View and download content attachments
+ **`read:blogpost:confluence`** – View blogposts
+ **`read:custom-content:confluence`** – View custom content
+ **`read:comment:confluence`** – View comments
+ **`read:template:confluence`** – View content templates
+ **`read:label:confluence`** – View labels
+ **`read:watcher:confluence`** – View content watchers
+ **`read:group:confluence`** – View groups
+ **`read:relation:confluence`** – View entity relationships
+ **`read:user:confluence`** – View user details
+ **`read:configuration:confluence`** – View Confluence settings
+ **`read:space:confluence`** – View space details
+ **`read:space.permission:confluence`** – View space permissions
+ **`read:space.property:confluence`** – View space properties
+ **`read:user.property:confluence`** – View user properties
+ **`read:space.setting:confluence`** – View space settings
+ **`read:analytics.content:confluence`** – View analytics for content
+ **`read:content.permission:confluence`** – Check content permissions
+ **`read:content.property:confluence`** – View content properties
+ **`read:content.restriction:confluence`** – View content restrictions
+ **`read:content.metadata:confluence`** – View content summaries
+ **`read:inlinetask:confluence`** – View tasks
+ **`read:task:confluence`** – View tasks
+ **`read:permission:confluence`** – View content restrictions and space permissions
+ **`read:whiteboard:confluence`** – View whiteboards
+ **`read:app-data:confluence`** – Read app data
+ *(Optional) ***`read:database:confluence`** – Read database
+ *(Optional) ***`read:embed:confluence `** – Read embeddings
+ *(Optional) ***`read:folder:confluence `** – Read folders
+ *(Optional) ***`read:email-address:confluence `** – Read email addresses
Then, select **Save**.
For more information, see [Implementing OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/oauth/getting-started/implementing-oauth-3lo/) and [Determining the scopes required for an operation](https://developer.atlassian.com/cloud/oauth/getting-started/determining-scopes/) in Atlassian Developer.
### Atlassian Admin Authentication
To ensure Amazon Q can access all user and group information from your Confluence (Cloud) instance, you must provide Atlassian admin credentials. These credentials allow Amazon Q to sync user information regardless of individual email visibility settings.
#### Get your Atlassian admin credentials
1. Sign in to the [Atlassian admin portal](https://admin.atlassian.com/)with administrator permissions.
1. Open the Administration app for your organization. The URL should look like: `https://admin.atlassian.com/o/{ORGANIZATION-UUID}/overview`
1. Choose **Settings**, then choose **API Keys**.
1. Choose **Create API key**\$1
1. Select all available scopes for the API key.
Note that the Confluence APIs that fetch user and group information require full scope access.
1. Copy and save both the **Organization ID** and **API Key**. Note that API keys expire. Monitor the expiration date and update your data source credentials before the key expires.
#### Get your Directory ID
1. Use the Atlassian Admin Workspace API to get your Directory ID. Run the following command:
```
curl --request POST \
--url 'https://api.atlassian.com/admin/v2/orgs/{ORGANIZATION-ID}/workspaces' \
--header 'Authorization: Bearer {API-KEY}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
```
1. In the API response, find the workspace entry that matches your Confluence Cloud instance. Look for `"type": "Confluence"`. Verify the workspace name matches your instance and then copy the directory value from the attributes section. If your instance isn't listed, use the pagination cursor in the `links.next` field to view additional pages.
```
curl --request POST \
--url 'https://api.atlassian.com/admin/v2/orgs/{ORGANIZATION-ID}/workspaces' \
--header 'Authorization: Bearer {API-KEY}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"cursor": "{NEXT-PAGE-TOKEN}"}'
```
#### Creating your Confluence data source
When creating your Confluence Cloud data source, provide these three values in your AWS Secrets Manager secret:
1. Admin API Key
1. Organization ID
1. Directory ID
For more information about Atlassian admin API scopes, see [Atlassian API scopes documentation](https://developer.atlassian.com/cloud/admin/scopes/).
For API details, see [Atlassian Admin Workspace API reference](https://developer.atlassian.com/cloud/admin/organization/rest/api-group-workspaces/#api-group-workspaces).
#### Updating your Confluence data source
To update an existing Confluence Cloud data source with new admin credentials, add the following key pairs to your AWS Secrets Manager secret:
1. adminApiKey, \$1Admin API Key\$1
1. organizationId, \$1Organization ID\$1
1. directoryId, \$1Directory ID\$1
For more information about Atlassian admin API scopes, see [Atlassian API scopes documentation](https://developer.atlassian.com/cloud/admin/scopes/).
For API details, see [Atlassian Admin Workspace API reference](https://developer.atlassian.com/cloud/admin/organization/rest/api-group-workspaces/#api-group-workspaces).
## Step 3: Retrieving Confluence (Cloud) client ID and client Secret
To connect Confluence (Cloud) to Amazon Q using OAuth 2.0 authentication, you need to provide a Confluence (Cloud) client ID and client secret. The following procedure shows you how to retrieve these.
**Note**
You must create an OAuth 2.0 app before you can retrieve the client ID and client secret. See [Configuring an OAuth 2.0 app integration](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-cloud-credentials.html#confluence-cloud-credentials-oauth-app) for more details.
**Retrieving Confluence (Cloud) client ID and client secret**
+ From the left navigation menu, choose **Settings**. Then, scroll down to **Authentication details** section and copy and save the following in a text editor of your choice:
+ Client ID – You will enter this as **App key** in the Amazon Q console.
+ Client Secret – You will enter this as **App secret** in the Amazon Q console.
![\[Screenshot of the OAuth application details page showing the client ID and client secret that need to be copied for API authentication with Confluence.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-15.png)
You will need these to generate your Confluence (Cloud) OAuth 2.0 token and also to connect Amazon Q to Confluence (Cloud).
For more information, see [Implementing OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/oauth/getting-started/implementing-oauth-3lo/) and [Determining the scopes required for an operation](https://developer.atlassian.com/cloud/oauth/getting-started/determining-scopes/) in Atlassian Developer.
## Step 4: Generating an Confluence (Cloud) access token
To connect Confluence (Cloud) to Amazon Q, you need to generate an access token. The following procedure outlines how to generate an access token in Confluence (Cloud).
**Generating your Confluence (Cloud) access token**
1. Log in to your account from the [Atlassian Developer page](https://developer.atlassian.com/).
1. Open the OAuth 2.0 app you want to generate a refresh token for.
1. From the left navigation menu, choose **Authorization** again. Then, for **OAuth 2.0 (3LO)**, choose **Configure**.
1. From the **Authorization** page, from **Authorization URL generator**, from **Granular Confluence API authorization URL**, copy the URL and save it in a text editor of your choice.
![\[Authorization page showing URL generator fields for User identity, Classic, and Granular Confluence API.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-16.png)
The URL is of the following format:
```
https://auth.atlassian.com/authorize?
audience=api.atlassian.com
&client_id=YOUR_CLIENT_ID
&scope=REQUESTED_SCOPE%20REQUESTED_SCOPE_TWO
&redirect_uri=https://YOUR_APP_CALLBACK_URL
&state=YOUR_USER_BOUND_VALUE
&response_type=code
&prompt=consent
```
1. In the saved authorization URL, update the `state=${YOUR_USER_BOUND_VALUE}` parameter value to any text of your choice. For example, `state=`*sample\$1text*.
For more information, see [What is the state parameter used for?](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#what-is-the-state-parameter-used-for-) in Atlassian Support.
1. Open a web browser of your choice. Then, paste the authorization URL you copied into the browser URL. On the page that opens up, make sure everything is correct and then select **Accept**.
![\[Atlassian account access request screen showing permissions and a warning about development mode.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-17.png)
You will be returned to your Confluence (Cloud) home page.
1. Copy the URL of the Confluence (Cloud) home page and save it in a text editor of your choice. The URL contains the authorization code for your application. You will need this code to generate your Confluence (Cloud) access token. The whole section after `code=` is the authorization code.
1. Navigate to Postman.
If you don't have Postman, you can also choose to use cURL to generate a Confluence (Cloud) access token. Use the following cURL command to do so:
```
curl --location 'https://auth.atlassian.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{"grant_type": "authorization_code",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"code": "AUTHORIZATION_CODE",
"redirect_uri": "YOUR_CALLBACK_URL"}'
```
1. On the Postman home page, select `POST` as the method, and then enter the following URL in the **Enter URL or paste text** box: `https://auth.atlassian.com/oauth/token`.
1. Then, select **Body** from the menu, and select **raw** **JSON**.
![\[API request interface showing POST method, URL, and JSON body with OAuth parameters.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-18.png)
1. In the text box, enter the following code extract, replacing the fields with your credential values:
```
{"grant_type": "authorization_code",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"code": "YOUR_AUTHORIZATION_CODE",
"redirect_uri": "https://YOUR_APP_CALLBACK_URL"}
```
1. Then, select **Send**. If everything is configured correctly, Postman will return an `access-token`. Copy the access token and save it using a text editor of your choice. You will need it to connect Confluence (Cloud) to Amazon Q.
For more information, see [Implementing OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/oauth/getting-started/implementing-oauth-3lo/) in Atlassian Developer.
## Step 5: Generating a Confluence (Cloud) refresh token
The access token you use to connect Confluence (Cloud) to Amazon Q using OAuth 2.0 authentication expires after 1 hour. When it does, you can either repeat the whole authorization process and generate a new access token. Or, you can choose to generate a refresh token. You can use the refresh token to regenerate a new access token when an existing access token expires.
To do this, you add a `%20offline_access` parameter to the end of the `scope` value in the authorization URL you used to generate your access token. The following procedure shows you how to generate a refresh token.
**Generating an Confluence (Cloud) refresh token**
1. Log in to your account from the [Atlassian Developer page](https://developer.atlassian.com/).
1. Open the OAuth 2.0 app you want to generate a refresh token for.
1. From the left navigation menu, choose **Authorization** again. Then, for **OAuth 2.0 (3LO)**, choose **Configure**.
1. From the **Authorization** page, from **Authorization URL generator**, from **Granular Confluence API authorization URL**, copy the URL and save it in a text editor of your choice.
![\[Authorization page showing URL generator fields for User identity, Classic, and Granular Confluence API.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-16.png)
1. In the saved authorization URL, update the `state=${YOUR_USER_BOUND_VALUE}` parameter value to any text of your choice. For example, `state=`*sample\$1text*.
For more information, see [What is the state parameter used for?](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#what-is-the-state-parameter-used-for-) in Atlassian Support.
1. Then, add the following text at the end of the `scope` value in your authorization URL: `%20offline_access` and copy it. For example:
```
https://auth.atlassian.com/authorize?
audience=api.atlassian.com
&client_id=YOUR_CLIENT_ID
&scope=REQUESTED_SCOPE%20REQUESTED_SCOPE_TWO%20offline_access
&redirect_uri=https://YOUR_APP_CALLBACK_URL
&state=YOUR_USER_BOUND_VALUE
&response_type=code
&prompt=consent
```
1. Open a web browser of your choice and paste the modified authorization URL you copied into the browser URL. On the page that opens up, make sure everything is correct and then select **Accept**.
![\[Atlassian account access request screen showing permissions and a warning about development mode.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-17.png)
You will be returned to the Confluence (Cloud) console.
1. Copy the URL of the Confluence (Cloud) home page and save it in a text editor of your choice. The URL contains the authorization code for your application. You will need this code to generate your Confluence (Cloud) refresh token. The whole section after `code=` is the authorization code.
1. Navigate to Postman.
If you don't have Postman, you can also choose to use cURL to generate a Confluence (Cloud) access token. Use the following cURL command to do so:
```
curl --location 'https://auth.atlassian.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{"grant_type": "authorization_code",
"client_id": "YOUR CLIENT ID",
"client_secret": "YOUR CLIENT SECRET",
"code": "AUTHORIZATION CODE",
"redirect_uri": "YOUR CALLBACK URL"}'
```
1. On the Postman home page, select `POST` as the method, and then enter the following URL in the **Enter URL or paste text** box: `https://auth.atlassian.com/oauth/token`.
1. Then, select **Body** from the menu, and select **raw** **JSON**.
![\[API request interface showing POST method, URL, and JSON body with OAuth parameters.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-18.png)
1. In the text box, enter the following code extract, replacing the fields with your credential values:
```
{"grant_type": "authorization_code",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"code": "YOUR_AUTHORIZATION_CODE",
"redirect_uri": "https://YOUR_APP_CALLBACK_URL"}
```
1. Then, select **Send**. If everything is configured correctly, Postman will return an `refresh-token`.
Copy the refresh token and save it using a text editor of your choice. You will need it to connect Confluence (Cloud) to Amazon Q.
For more information, see [Implementing a Refresh Token Flow](https://developer.atlassian.com/cloud/oauth/getting-started/refresh-tokens/) in Atlassian Developer.
## Step 6: Generating a new Confluence (Cloud) access token using a refresh token
You can use the refresh token you generated to create a new access token-refresh token pair when an existing access token expires. The following procedure shows you how to generate a refresh token.
**Generating an Confluence (Cloud) access token-refresh token pair**
1. Copy the refresh token you generated following the steps in [Step 5: Generating a Confluence (Cloud) refresh token](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-cloud-credentials.html#confluence-cloud-credentials-refresh).
1. Navigate to Postman.
If you don't have Postman, you can also choose to use cURL to generate a new Confluence (Cloud) access token. Use the following cURL command to do so:
```
curl --location 'https://auth.atlassian.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{"grant_type": "refresh_token",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"refresh_token": "YOUR_REFRESH_TOKEN"}'
```
1. On the Postman home page, select `POST` as the method, and then enter the following URL in the **Enter URL or paste text** box: `https://auth.atlassian.com/oauth/token`.
1. Then, select **Body** from the menu, and select **raw** **JSON**.
![\[Screenshot of the Postman interface showing how to set up a POST request to refresh an access token using the refresh token.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/confluence-20.png)
1. In the text box, enter the following code extract, replacing the fields with your credential values:
```
{"grant_type": "refresh_token",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"refresh_token": "YOUR REFRESH TOKEN"}
```
1. Then, select **Send**. If everything is configured correctly, Postman will return a new access token-refresh token pair in the following format:
```
{
"access_token": "string,
"expires_in": "expiry time of access_token in second",
"scope": "string",
"refresh_token": "string"
}
```
For more information, see [Implementing a Refresh Token Flow](https://developer.atlassian.com/cloud/oauth/getting-started/refresh-tokens/) and [How do I get a new access token, if my access token expires or is revoked? ](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#how-do-i-get-a-new-access-token--if-my-access-token-expires-or-is-revoked-)in Atlassian Developer.
# How Amazon Q works with Confluence (Cloud) access and refresh tokens
The following are important points to note about using Confluence (Cloud) access and refresh tokens with Amazon Q:
+ If a Confluence (Cloud) access token-refresh token pair you use to connect to Amazon Q are expired or invalid, the Amazon Q sync process fails. If this happens, you need to generate and provide a new pair of tokens.
+ If your access token is valid but you have an invalid refresh token, Amazon Q will sync data until the access token expires (up to 1 hour). After the access token expires, you won't be able to re-generate an access token-refresh token pair using the expired refresh token. When both access token and refresh token expire, the Amazon Q Confluence (Cloud) data source connector stops syncing.
+ If an access token expires during the Confluence (Cloud) connector sync process, the connector internally regenerates a new pair of tokens using the existing refresh token (if the provided refresh token is valid). After regenerating the new pair of tokens, the old pair is invalidated by Confluence (Cloud) and can't be re-used. To sync documents again after the connector auto-regenerates tokens, you must provide a new access token-refresh token pair.
+ If you use OAuth, select **Rotate secret** if you want Amazon Q to rotate the secret automatically so that you don’t have to manually update the secret every time before you sync.
+ As a best practice, use Confluence (Cloud) OAuth and the **Rotate secret** feature for the Amazon Q connector.
# Checking Confluence (Cloud) connectivity
Before you sync your Confluence (Cloud) data source connector after [configuring it](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-cloud-console.html), we recommend you check the connection between Amazon Q Business and Confluence (Cloud). The following are the cURL commands you need to check Confluence (Cloud) connectivity.
**Topics**
+ [
## Checking basic authentication connectivity
](#confluence-cloud-connection-check-basic)
## Checking basic authentication connectivity
To check connectivity for a Confluence (Cloud) data source connector using basic authentication, use the following cURL command:
```
curl --location 'https://{
"username": "Confluence account user name",
"password": "Confluence API token"
}If you use OAuth 2.0 authentication, the secret must contain a JSON structure with the following keys: {
"confluenceAppKey": "app key for your Confluence account",
"confluenceAppSecret": "app secret from your Confluence token",
"confluenceAccessToken": "access token created in Confluence",
"confluenceRefreshToken": "refresh token created in Confluence"
} | Yes |
| `version` | The version of this template that's currently supported. | `string` | No |
## Confluence (Cloud) JSON schema
The following is the Confluence (Cloud) JSON schema:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["CONFLUENCEV2", "CONFLUENCE"]
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"hostUrl": {
"type": "string",
"pattern": "https:.*"
},
"type": {
"type": "string",
"enum": ["SAAS"]
},
"authType": {
"type": "string",
"enum": ["Basic", "OAuth2"]
}
},
"required": ["hostUrl", "type", "authType"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"space": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"page": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"blog": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"fieldForUserId": {
"type": "string"
},
"inclusionSpaceKeyFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionSpaceKeyFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"pageTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"blogTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"commentTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"attachmentTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"isCrawlPersonalSpace": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlArchivedSpace": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlArchivedPage": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlPage": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlBlog": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlPageComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlPageAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlBlogComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlBlogAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionUrlPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionUrlPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"proxyHost": {
"type": "string"
},
"proxyPort": {
"type": "string"
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"type",
"syncMode",
"secretArn",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
## Confluence (Cloud) JSON schema example
The following is the Confluence (Cloud) JSON schema example:
```
{
"type": "CONFLUENCEV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-confluence-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"hostUrl": "https://mycompany.atlassian.net",
"type": "SAAS",
"authType": "OAuth2"
}
},
"repositoryConfigurations": {
"space": {
"fieldMappings": [
{
"indexFieldName": "space_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"page": {
"fieldMappings": [
{
"indexFieldName": "page_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"blog": {
"fieldMappings": [
{
"indexFieldName": "blog_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"isCrawlAcl": "true",
"fieldForUserId": "user_id",
"inclusionSpaceKeyFilter": ["SPACE1", "SPACE2"],
"exclusionSpaceKeyFilter": ["SPACE3"],
"pageTitleRegEX": ["^.*$"],
"blogTitleRegEX": ["^.*$"],
"commentTitleRegEX": ["^.*$"],
"attachmentTitleRegEX": ["^.*$"],
"isCrawlPersonalSpace": "false",
"isCrawlArchivedSpace": "false",
"isCrawlArchivedPage": "true",
"isCrawlPage": "true",
"isCrawlBlog": "true",
"isCrawlPageComment": "false",
"isCrawlPageAttachment": "false",
"isCrawlBlogComment": "true",
"isCrawlBlogAttachment": "true",
"maxFileSizeInMegaBytes": "50",
"inclusionFileTypePatterns": ["*.pdf", "*.docx"],
"exclusionFileTypePatterns": ["*.tmp"],
"inclusionUrlPatterns": ["*"],
"exclusionUrlPatterns": ["*.tmp"],
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
```
# Connecting Amazon Q Business to Confluence (Cloud) using AWS CloudFormation
Using the CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
**Topics**
+ [
## Confluence configuration properties
](#confluence-configuration-keys)
+ [
## Confluence (Cloud) JSON schema for using the configuration property with AWS CloudFormation
](#confluence-cloud-cfn-json)
+ [
## Confluence (Cloud) YAML schema for using the configuration property with AWS CloudFormation
](#confluence-cloud-cfn-yaml)
## Confluence configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has a sub-property called `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | This is the endpoint information for the data source. This is a sub-property for the connectionConfiguration. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-cloud-cfn.html) | Yes |
| `hostUrl` | The URL for your Confluence instance. For example, https://example.confluence.com. | `string` Specify the URL in the pattern `https://*` | Yes |
| `type` | The hosting method for your Confluence instance. | `string` The allowed values are `SAAS` or `ON_PREM`. | Yes |
| `authType` | The authentication method for your Confluence instance. | `string` The allowed values are `Basic` or `OAuth2`. | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-cloud-cfn.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-cloud-cfn.html) | A list of objects that map the attributes or field names of your Confluence spaces, pages, blogs, comments, and attachments to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-cloud-cfn.html) | No |
| `indexFieldName` | The field name of your Confluence spaces, pages, blogs, comments, or attachments. | `string` | Yes |
| `indexFieldType` | The field type of your Confluence spaces, pages, blogs, comments, or attachments. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your Confluence spaces, pages, blogs, comments, or attachments. | `string` | Yes |
| `dateFieldFormat` | The date format of your Confluence spaces, pages, blogs, comments, or attachments. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-cloud-cfn.html) | Yes |
| `isCrawlAcl` | Specify true to crawl access control information from documents. | `boolean` | No |
| `isRotateSecret` | Specify true if you want to automatically rotate the secret. | `boolean` | No |
| `fieldForUserId` | Specify field to use for UserId for ACL crawling. | `string` | No |
| `proxyHost` | The host where the web proxy is required. The host name should be without protocol (http:// or https://). | `string` | Yes |
| `proxyPort` | Port used by the host URL transport protocol. The port number should be a numeric value between 0 and 65535. | `string` | Yes |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` The allowed values are numbers between greater than 0 and less than or equal to 50. | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-cloud-cfn.html) | A list of regular expression patterns to include and/or exclude certain files in your Confluence data source. Files that match the patterns are included in the index. Files that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence and the file isn't included in the index. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-cloud-cfn.html) | Specify true to index files in your Confluence personal spaces, pages, blogs, page comments, page attachments, blog comments, and blog attachments. | `boolean` | No |
| `type` | The type of data source. We recommend that you use CONFLUENCEV2 as your data source type. | `string` Valid values are `CONFLUENCEV2` and `CONFLUENCE`. | Yes |
| `enableIdentityCrawler` | Specify `true` to activate identity crawler. Identity crawler is activated by default. See [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler) for more information. | `boolean` | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` Valid values are `FORCED_FULL_CRAWL` and `FULL_CRAWL`. You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-cloud-cfn.html) | Yes |
| `secretARN` | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains the key-value pairs required to connect to your Confluence instance. | `string` The minimum length is 20 and the maximum length is 2,048 characters. If you use basic authentication, the secret must contain a JSON structure with the following keys: {
"username": "Confluence account user name",
"password": "Confluence API token"
}If you use OAuth 2.0 authentication, the secret must contain a JSON structure with the following keys: {
"confluenceAppKey": "app key for your Confluence account",
"confluenceAppSecret": "app secret from your Confluence token",
"confluenceAccessToken": "access token created in Confluence",
"confluenceRefreshToken": "refresh token created in Confluence"
} | Yes |
| `version` | The version of this template that's currently supported. | `string` | No |
## Confluence (Cloud) JSON schema for using the configuration property with AWS CloudFormation
Confluence (Cloud) JSON schema
The following is the Confluence (Cloud) JSON schema and examples for the configuration property for AWS CloudFormation.
**Topics**
+ [
### Confluence (Cloud) JSON schema for using the configuration property with AWS CloudFormation
](#confluence-cloud-cfn-json-schema)
+ [
### Confluence (Cloud) JSON schema example for using the configuration property with AWS CloudFormation
](#confluence-cloud-cfn-json-example)
### Confluence (Cloud) JSON schema for using the configuration property with AWS CloudFormation
Confluence (Cloud) JSON schema
The following is the Confluence (Cloud) JSON schema for the configuration property for CloudFormation
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["CONFLUENCEV2", "CONFLUENCE"]
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"hostUrl": {
"type": "string",
"pattern": "https:.*"
},
"type": {
"type": "string",
"enum": ["SAAS"]
},
"authType": {
"type": "string",
"enum": ["Basic", "OAuth2"]
}
},
"required": ["hostUrl", "type", "authType"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"space": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"page": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"blog": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"fieldForUserId": {
"type": "string"
},
"inclusionSpaceKeyFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionSpaceKeyFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"pageTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"blogTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"commentTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"attachmentTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"isCrawlPersonalSpace": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlArchivedSpace": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlArchivedPage": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlPage": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlBlog": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlPageComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlPageAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlBlogComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlBlogAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionUrlPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionUrlPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"proxyHost": {
"type": "string"
},
"proxyPort": {
"type": "string"
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"type",
"syncMode",
"secretArn",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
### Confluence (Cloud) JSON schema example for using the configuration property with AWS CloudFormation
Confluence (Cloud) JSON schema example
The following is the Confluence (Cloud) JSON schema example for the configuration property for CloudFormation
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "CloudFormation CONFLUENCE Data Source Template",
"Resources": {
"DataSourceConfluence": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": "app12345-1234-1234-1234-123456789012",
"IndexId": "indx1234-1234-1234-1234-123456789012",
"DisplayName": "MyConfluenceDataSource",
"RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role",
"Configuration": {
"type": "CONFLUENCEV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-confluence-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"hostUrl": "https://mycompany.atlassian.net",
"type": "SAAS",
"authType": "OAuth2"
}
},
"repositoryConfigurations": {
"space": {
"fieldMappings": [
{
"indexFieldName": "space_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"page": {
"fieldMappings": [
{
"indexFieldName": "page_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"blog": {
"fieldMappings": [
{
"indexFieldName": "blog_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"isCrawlAcl": "true",
"fieldForUserId": "user_id",
"inclusionSpaceKeyFilter": ["SPACE1", "SPACE2"],
"exclusionSpaceKeyFilter": ["SPACE3"],
"pageTitleRegEX": ["^.*$"],
"blogTitleRegEX": ["^.*$"],
"commentTitleRegEX": ["^.*$"],
"attachmentTitleRegEX": ["^.*$"],
"isCrawlPersonalSpace": "false",
"isCrawlArchivedSpace": "false",
"isCrawlArchivedPage": "true",
"isCrawlPage": "true",
"isCrawlBlog": "true",
"isCrawlPageComment": "false",
"isCrawlPageAttachment": "false",
"isCrawlBlogComment": "true",
"isCrawlBlogAttachment": "true",
"maxFileSizeInMegaBytes": "50",
"inclusionFileTypePatterns": ["*.pdf", "*.docx"],
"exclusionFileTypePatterns": ["*.tmp"],
"inclusionUrlPatterns": ["*"],
"exclusionUrlPatterns": ["*.tmp"],
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
}
}
}
}
```
## Confluence (Cloud) YAML schema for using the configuration property with AWS CloudFormation
Confluence (Cloud) YAML schema
The following is the Confluence (Cloud) YAML schema and examples for the configuration property for AWS CloudFormation:
**Topics**
+ [
### Confluence (Cloud) YAML schema for using the configuration property with AWS CloudFormation
](#confluence-cloud-cfn-yaml-schema)
+ [
### Confluence (Cloud) YAML schema example for using the configuration property with AWS CloudFormation
](#confluence-cloud-cfn-yaml-example)
### Confluence (Cloud) YAML schema for using the configuration property with AWS CloudFormation
Confluence (Cloud) YAML schema
The following is the Confluence (Cloud) YAML schema for the configuration property for CloudFormation.
```
type: object
properties:
type:
type: string
enum:
- CONFLUENCEV2
- CONFLUENCE
syncMode:
type: string
enum:
- FULL_CRAWL
- FORCED_FULL_CRAWL
secretArn:
type: string
minLength: 20
maxLength: 2048
enableIdentityCrawler:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
connectionConfiguration:
type: object
properties:
repositoryEndpointMetadata:
type: object
properties:
hostUrl:
type: string
pattern: "https:.*"
type:
type: string
enum:
- SAAS
authType:
type: string
enum:
- Basic
- OAuth2
required:
- hostUrl
- type
- authType
required:
- repositoryEndpointMetadata
repositoryConfigurations:
type: object
properties:
space:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- fieldMappings
page:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- fieldMappings
blog:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- fieldMappings
comment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- fieldMappings
attachment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- fieldMappings
additionalProperties:
type: object
properties:
isCrawlAcl:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
fieldForUserId:
type: string
inclusionSpaceKeyFilter:
type: array
items:
type: string
exclusionSpaceKeyFilter:
type: array
items:
type: string
pageTitleRegEX:
type: array
items:
type: string
blogTitleRegEX:
type: array
items:
type: string
commentTitleRegEX:
type: array
items:
type: string
attachmentTitleRegEX:
type: array
items:
type: string
isCrawlPersonalSpace:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlArchivedSpace:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlArchivedPage:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlPage:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlBlog:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlPageComment:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlPageAttachment:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlBlogComment:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlBlogAttachment:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
maxFileSizeInMegaBytes:
type: string
inclusionFileTypePatterns:
type: array
items:
type: string
exclusionFileTypePatterns:
type: array
items:
type: string
inclusionUrlPatterns:
type: array
items:
type: string
exclusionUrlPatterns:
type: array
items:
type: string
proxyHost:
type: string
proxyPort:
type: string
enableDeletionProtection:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
default: false
deletionProtectionThreshold:
type: string
default: "15"
required: []
version:
type: string
anyOf:
- pattern: 1.0.0
required:
- type
- syncMode
- secretArn
- connectionConfiguration
- repositoryConfigurations
- additionalProperties
```
### Confluence (Cloud) YAML schema example for using the configuration property with AWS CloudFormation
Confluence (Cloud) JSON schema example
The following is the Confluence (Cloud) YAML example for the Configuration property for CloudFormation:
```
AWSTemplateFormatVersion: "2010-09-09"
Description: CloudFormation CONFLUENCE Data Source Template
Resources:
DataSourceConfluence:
Type: AWS::QBusiness::DataSource
Properties:
ApplicationId: app12345-1234-1234-1234-123456789012
IndexId: indx1234-1234-1234-1234-123456789012
DisplayName: MyConfluenceDataSource
RoleArn: arn:aws:iam::123456789012:role/qbusiness-data-source-role
Configuration:
type: CONFLUENCEV2
syncMode: FULL_CRAWL
secretArn: arn:aws:secretsmanager:us-west-2:123456789012:secret:my-confluence-secret
enableIdentityCrawler: "true"
connectionConfiguration:
repositoryEndpointMetadata:
hostUrl: https://mycompany.atlassian.net
type: SAAS
authType: OAuth2
repositoryConfigurations:
space:
fieldMappings:
- indexFieldName: space_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
page:
fieldMappings:
- indexFieldName: page_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
blog:
fieldMappings:
- indexFieldName: blog_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
comment:
fieldMappings:
- indexFieldName: comment_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
attachment:
fieldMappings:
- indexFieldName: attachment_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
additionalProperties:
isCrawlAcl: "true"
fieldForUserId: user_id
inclusionSpaceKeyFilter:
- SPACE1
- SPACE2
exclusionSpaceKeyFilter:
- SPACE3
pageTitleRegEX:
- "^.*$"
blogTitleRegEX:
- "^.*$"
commentTitleRegEX:
- "^.*$"
attachmentTitleRegEX:
- "^.*$"
isCrawlPersonalSpace: "false"
isCrawlArchivedSpace: "false"
isCrawlArchivedPage: "true"
isCrawlPage: "true"
isCrawlBlog: "true"
isCrawlPageComment: "false"
isCrawlPageAttachment: "false"
isCrawlBlogComment: "true"
isCrawlBlogAttachment: "true"
maxFileSizeInMegaBytes: "50"
inclusionFileTypePatterns:
- "*.pdf"
- "*.docx"
exclusionFileTypePatterns:
- "*.tmp"
inclusionUrlPatterns:
- "*"
exclusionUrlPatterns:
- "*.tmp"
enableDeletionProtection: "false"
deletionProtectionThreshold: "15"
```
# How Amazon Q Business connector crawls Confluence (Cloud) ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect a Confluence (Cloud) data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your Confluence (Cloud) instance. If you choose to activate ACL crawling, the information can be used to filter chat responses based your end users' document access level.
The connector crawls the following Confluence resources:
+ **Spaces** – A collection of related pages, blogs, and attachments. Space permissions apply to all documents in the space by default.
+ **Pages** – Documents in a space where users create and manage content. Pages can contain text, images, tables, and multimedia elements, and can have nested pages. Each page is considered a single document. Pages can be restricted to specific users and groups in the space. A nested page inherits restrictions from the parent page, and can have its own restrictions.
+ **Blogs** – Content similar to pages, typically used for updates or announcements. Each blog post is considered as a single document. Blogs can be restricted to specific users and groups in the space.
+ **Comments** – Feedback and discussions on pages or blog post content. Comments are visible to viewers of the page or post.
+ **Attachments** – Files uploaded to pages or blog posts, such as images and documents.
The connector also crawls user principal information (local user alias, local group and federated group identity configurations) and its permissions for each configured space. The Confluence (Cloud) connector does not support crawling macros, whiteboards, or databases.
The connector updates ACL changes each time it crawls your data source content. To ensure that the correct users have access to the correct content, regularly re-sync your data source to capture any ACL updates.
You configure user and group access to spaces using the space permissions page. For pages and blogs, you use the restrictions page. For more information about space permissions, see [Space Permissions Overview](https://confluence.atlassian.com/doc/space-permissions-overview-139521.html) on the Confluence Support website. For more information about page and blog restrictions, see [ Page Restrictions ](https://confluence.atlassian.com/doc/page-restrictions-139414.html) on the Confluence Support website.
**Important**
For user context filtering to work correctly, users' visibility must be set to **Anyone**. For more information, see [Set your email visibility](https://support.atlassian.com/confluence-cloud/docs/configure-user-email-visibility/) in Atlassian Developer Documentation.
The group and user IDs are mapped as follows:
+ `_group_ids` – Group names are present on spaces, pages, and blogs where there are restrictions. They're mapped from the name of the group in Confluence . Group names are always lower case.
+ `_user_id` – User names are present on the space, page, or blog where there are restrictions. They're mapped depending on the type of Confluence instance that you are using.
For Confluence (Cloud) – The `_user_id` is the account ID of the user.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Amazon Q Business Confluence (Cloud) data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application environment and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes-types.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Confluence connector supports the following entities and the associated reserved and custom attributes.
**Important**
If you map any Confluence (Cloud) field to Amazon Q document title and document body fields, Amazon Q will generate responses from data in the document title and body.
**Topics**
+ [
## Space
](#confluence-field-mappings-space)
+ [
## Page
](#confluence-field-mappings-page)
+ [
## Blog
](#confluence-field-mappings-blog)
+ [
## Comment
](#confluence-field-mappings-comment)
+ [
## Attachment
](#confluence-field-mappings-attachment)
## Space
| Confluence field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| spaceName | cf\$1sp\$1document\$1title | Custom | String |
| itemType | \$1category | Default | String |
| url | \$1source\$1uri | Default | String |
| spaceKey | cf\$1space\$1key | Custom | String |
| description | cf\$1description | Custom | String |
| spaceType | cf\$1type | Custom | String |
## Page
| Confluence field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | \$1cf\$1page\$1document\$1title | Custom | String |
| authors | \$1authors | Default | String list |
| createdDate | \$1created\$1at | Default | Date |
| modifiedDate | \$1last\$1updated\$1at | Default | Date |
| labels | cf\$1labels | Custom | String list |
| version | cf\$1version | Custom | Long (numeric) |
| itemType | \$1category | Default | String |
| spaceKey | cf\$1space\$1key | Custom | String |
| spaceName | cf\$1space\$1name | Custom | String |
| url | \$1source\$1uri | Default | String |
| status | cf\$1status | Custom | String |
| parentId | cf\$1parent\$1id | Custom | String |
## Blog
| Confluence field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | cf\$1bg\$1document\$1title | Custom | String |
| author | \$1authors | Default | String list |
| publishedDate | \$1created\$1at | Default | Date |
| labels | \$1source\$1uri | Default | String |
| version | cf\$1version | Custom | Long (numeric) |
| itemType | \$1category | Custom | String |
| spaceKey | cf\$1space\$1key | Custom | String |
| modifiedDate | \$1last\$1updated\$1at | Default | Date |
| spaceName | cf\$1space\$1name | Custom | String |
| status | cf\$1status | Custom | String |
| url | \$1source\$1uri | Default | String |
| parentId | cf\$1parent\$1id | Custom | String |
## Comment
| Confluence field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | cf\$1cmt\$1document\$1title | Custom | String |
| author | \$1authors | Default | String list |
| createdDate | \$1created\$1at | Default | Date |
| version | cf\$1version | Custom | Long (numeric) |
| itemType | \$1category | Default | String |
| spaceKey | cf\$1space\$1key | Custom | String |
| spaceName | cf\$1space\$1name | Custom | String |
| contentType | cf\$1content\$1type | Custom | String |
| url | \$1source\$1uri | Default | String |
| parentId | cf\$1parent\$1id | Custom | String |
| status | cf\$1status | Custom | String |
## Attachment
| Confluence field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| fileName | cf\$1attachment\$1document\$1title | Custom | String |
| author | \$1authors | Default | String list |
| createdDate | \$1created\$1at | Default | Date |
| labels | cf\$1labels | Custom | String list |
| version | cf\$1version | Custom | Long (numeric) |
| itemType | \$1category | Default | String |
| spaceKey | cf\$1space\$1key | Custom | String |
| contentType | cf\$1content\$1type | Custom | String |
| modifiedDate | \$1last\$1updated\$1at | Default | Date |
| fileSize | cf\$1file\$1size | Custom | Long (numeric) |
| fileType | cf\$1attachment\$1file\$1type | Custom | String |
| spaceName | cf\$1space\$1name | Custom | String |
| documentId | \$1document\$1id | Default | String list |
| url | \$1source\$1uri | Default | String |
| parentId | cf\$1parent\$1id | Custom | String |
| attachmentComment | cf\$1attachment\$1comment | Custom | String |
| status | cf\$1status | Custom | String |
# IAM role for Amazon Q Confluence (Cloud) connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Understand error codes in the Amazon Q Business Confluence (Cloud) connector
Error codes
The following table provides information about error codes you may see for the Confluence (Cloud) connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| CNF-5500 | Null/empty username. | Provide username. |
| CNF-5501 | Error validating credentials due to Invalid username or password. | Provide valid username/password |
| CNF-5502 | Null/empty confluence AppKey. | Provide confluence AppKey. |
| CNF-5503 | Null/empty confluence Secret. | Provide confluence Secret. |
| CNF-5504 | Null/empty Client Access Token. | Provide Client Access Token. |
| CNF-5505 | Null/empty Client Refresh Token | Provide Client Refresh Token |
| CNF-5506 | Incorrect auth type. | Auth type should be Basic or OAuth2 or Personal-token. |
| CNF-5507 | Null/empty auth type. | Auth Type should not be null or empty value. |
| CNF-5508 | Empty/null host URL. | Host Url should not be null or empty value. |
| CNF-5509 | Null/empty crawl type. | Crawl Type should not be null or empty value. |
| CNF-5510 | Null/empty Repository Configurations. | Repository Configurations should not be null or empty value. |
| CNF-5511 | Incorrect type. | type should be SAAS or ON\$1PREM. |
| CNF-5512 | Invalid inclusion file type patterns. | Provide the correct inclusion patterns. |
| CNF-5513 | Invalid exclusion file type patterns. | Provide the correct exclusion patterns. |
| CNF-5514 | Invalid regex patterns. | Provide the correct regex patterns. |
| CNF-5515 | Error validating credentials due to invalid username or password. | Provide valid username and password. |
| CNF-5516 | Error validating credentials due to invalid client id or client secret. | Provide valid client id and client secret. |
| CNF-5517 | Error validating crawl type. | Provide valid crawl type. |
| CNF-5518 | Invalid URI. | Provide valid URI. |
| CNF-5519 | Null/empty DataSourceFieldName in Space Entity. | Provide value for DataSourceFieldName in Space Entity. |
| CNF-5520 | Null/empty IndexFieldName in Blog Entity. | Provide value for IndexFieldName in Blog Entity. |
| CNF-5521 | Null/empty IndexFieldType in Space Entity. | Provide value for IndexFieldType in Space Entity. |
| CNF-5522 | Null/empty password. | Provide password. |
| CNF-5523 | Incorrect auth type. | Auth type should be Basic or OAuth2. |
| CNF-5524 | Null/empty DataSourceFieldName in Page Entity. | Provide value for DataSourceFieldName in Page Entity. |
| CNF-5525 | Null/empty DataSourceFieldName in Blog Entity | Please provide value for DataSourceFieldName in Blog Entity |
| CNF-5526 | Null/empty DataSourceFieldName in Comment Entity. | Provide value for DataSourceFieldName in Comment Entity. |
| CNF-5527 | Null/empty DataSourceFieldName in Attachment Entity. | Provide value for DataSourceFieldName in Attachment Entity. |
| CNF-5528 | Null/empty IndexFieldName. | IndexFieldName field can't be null or empty value. |
| CNF-5529 | Null/empty IndexFieldName in Space Entity. | Provide value for IndexFieldName in Space Entity. |
| CNF-5530 | Null/empty IndexFieldName in Page Entity | Please provide value for IndexFieldName in Page Entity |
| CNF-5531 | Invalid isCrawlPersonalSpace value. | isCrawlPersonalSpace should be a boolean value true or false. |
| CNF-5532 | Invalid isCrawlArchivedSpace value. | isCrawlArchivedSpace should be a boolean value true or false. |
| CNF-5533 | Invalid isCrawlArchivedPage value. | isCrawlArchivedPage should be a boolean value true or false. |
| CNF-5534 | Invalid isCrawlPage value. | isCrawlPage should be a boolean value true or false. |
| CNF-5535 | Invalid isCrawlBlogComment value. | isCrawlBlogComment should be a boolean value true or false. |
| CNF-5536 | Invalid isCrawlBlogComment value. | isCrawlBlogComment should be a boolean value true or false. |
| CNF-5537 | Invalid isCrawlBlogAttachment value. | isCrawlBlogAttachment should be a boolean value true or false. |
| CNF-5538 | Error validating on protocol. | Provide valid protocol. |
| CNF-5539 | Null/empty IndexFieldName in Comment Entity. | Provide value for IndexFieldName in Comment Entity. |
| CNF-5540 | Null/empty Personal Access Token. | Provide Personal Access Token. |
| CNF-5541 | Invalid OAuth value. | Give a valid OAuth URL. |
| CNF-5542 | Invalid Space value. | Give a valid Space URL. |
| CNF-5543 | Archived Space Exception. | Check Archived Space. |
| CNF-5544 | JSON Exception for Space. | Check Space. |
| CNF-5545 | JSON Exception for Comment. | Check Comment. |
| CNF-5546 | JSON Exception for Comment. | Check Comment. |
| CNF-5547 | JSON Exception for Comment. | Check Comment. |
| CNF-5548 | JSON Exception for Attachment. | Check Attachment. |
| CNF-5549 | JSON Exception for Blog. | Check Blog. |
| CNF-5550 | JSON Exception for Page. | Check Page. |
| CNF-5551 | JSON Exception for Label. | Check Label. |
| CNF-5552 | JSON Exception for ACL. | Check ACL. |
| CNF-5553 | JSON Exception for Groups. | Check Groups. |
| CNF-5554 | JSON Exception for Group Members. | Check Group Members. |
| CNF-5555 | JSON Exception for Space Group. | Check Space Group. |
| CNF-5556 | Exception in CommentItem. | Check the CommentItem class. |
| CNF-5557 | Invalid isCrawlPageComment value. | isCrawlPageComment should be a boolean value true or false. |
| CNF-5558 | Invalid isCrawlPageAttachment value. | isCrawlPageAttachment should be a boolean value true or false. |
| CNF-5559 | Null/empty Repository Configurations. | Repository Configurations should not be null or empty value. |
| CNF-5560 | Null/empty IndexFieldName in Attachment. | Please provide value for IndexFieldName in Attachment Entity. |
| CNF-5561 | Invalid proxy url. | Proxy url should not contain http: or https. |
| CNF-5562 | Null/Empty proxy port. | Provide a valid proxy port. |
| CNF-5563 | Invalid Host URL. | Provide valid Host URL. |
| CNF-5564 | Invalid proxy port value. | Provide a valid proxy port. |
| CNF-5565 | Confluence server not reachable. | Provide a valid proxy and server details. |
| CNF-5566 | Null/empty IndexFieldType in Page Entity. | Provide value for IndexFieldType in Page Entity. |
| CNF-5567 | Null/empty IndexFieldType in Blog Entity. | Provide value for IndexFieldType in Blog Entity. |
| CNF-5568 | Null/empty IndexFieldType in Comment Entity. | Provide value for IndexFieldType in Comment Entity. |
| CNF-5569 | Null/empty IndexFieldType in Attachment. | Provide value for IndexFieldType in Attachment. Entity |
| CNF-5570 | JSON Exception for Content Ancestors. | Check your Ancestors. |
| CNF-5571 | Invalid Host URL Pattern. | Provide valid Host URL Pattern. |
| CNF-5572 | Error validating credentials due to Invalid access or refresh token. | Invalid AccessToken/RefreshToken. |
# Connecting Confluence (Server/Data Center) to Amazon Q Business
Confluence (Server/Data Center)
Atlassian Confluence is a collaborative work-management tool designed for sharing, storing, and working on project planning, software development, and product management. You can connect Confluence (Server/Data Center) instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# Known limitations for the Amazon Q Business Confluence (Server/Data Center) connector
](confluence-server-limitations.md)
+ [
# Confluence (Server/Data Center) connector overview
](confluence-server-overview.md)
+ [
# Prerequisites for connecting Amazon Q to Confluence (Server/Data Center)
](confluence-server-prereqs.md)
+ [
# Checking Confluence (Server/Data Center) connectivity
](confluence-server-connection-check.md)
+ [
# Connecting Amazon Q Business to Confluence (Server/Data Center) using the console
](confluence-server-console.md)
+ [
# Connecting Amazon Q Business to Confluence (Server/Data Center) using APIs
](confluence-server-api.md)
+ [
# Connecting Amazon Q Business to Confluence (Server/Data Center) using AWS CloudFormation
](confluence-server-cfn.md)
+ [
# How Amazon Q Business connector crawls Confluence (Server/Data Center) ACLs
](confluence-server-user-management.md)
+ [
# Amazon Q Business Confluence (Server/Data Center) data source connector field mappings
](confluence-server-field-mappings.md)
+ [
# IAM role for Amazon Q Confluence (Server/Data Center) connector
](confluence-server-iam-role.md)
+ [
# Understand error codes in the Amazon Q Business Confluence (Server/Data Center) connector
](confluence-server-error-codes.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Amazon Q Business Confluence (Server/Data Center) connector
Known limitations
The Amazon Q Confluence (Server/Data Center) connector has the following known limitation:
+ Because Amazon Q Business uses email addresses as unique identifiers, each user must have a unique email address.
+ The Confluence (Server/Data Center) connector may not accurately differentiate between Confluence users with duplicate email addresses when mapping access control lists (ACLs). This can lead to inconsistent search results, in which a user might be able to see restricted content intended for one Confluence user with a shared email, but not other restricted content intended for a different Confluence user with the same email.
# Confluence (Server/Data Center) connector overview
The following table gives an overview of the Amazon Q Business Confluence (Server/Data Center) connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-server-overview.html)
# Prerequisites for connecting Amazon Q to Confluence (Server/Data Center)
Before you begin, make sure that you have completed the following prerequisites.
**In Confluence Server/Data Center, make sure you have:**
+ Copied your Confluence instance URL. For example: *https://example.confluence.com*. You need your Confluence instance URL to connect to Amazon Q.
+ Configured basic authentication credentials containing a username (username used to log into Confluence) and password (Confluence Server/Data Center password) to allow Amazon Q to connect to your Confluence Server/Data Center instance.
+ **Optional:** Configured OAuth 2.0 credentials containing a Confluence app key, Confluence app secret, Confluence access token, and Confluence refresh token to allow Amazon Q to connect to your Confluence instance. If your access token expires, you can either use the refresh token to regenerate your access token and refresh token pair, or you can repeat the authorization process.
+ **Optional:** Configured a Personal Access Token (PAT) containing a Confluence token to allow Amazon Q to connect to your Confluence Server/Data Center instance. For information about how to create a PAT token, see [Using Personal Access Tokens](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html) on the Atlassian website.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ If you want to have Amazon Q automatically rotate your secret, ensure that your IAM role includes the `secretsmanager:PutSecretValue` and `secretsmanager:UpdateSecret` permissions.
+ Stored your Confluence (Server/Data Center) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Checking Confluence (Server/Data Center) connectivity
Before you sync your Confluence (Server/Data Center) data source connector after [configuring it](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-server-console.html), we recommend you check the connection between Amazon Q Business and Confluence (Server/Data Center). The following are the cURL commands you need to check Confluence (Server/Data Center) connectivity.
**Topics**
+ [
## Checking basic authentication connectivity
](#confluence-server-connection-check-basic)
+ [
## Checking personal access token connectivity
](#confluence-server-connection-check-pat)
## Checking basic authentication connectivity
To check connectivity for a Confluence (Server/Data Center) data source connector using basic authentication, use the following cURL command:
```
curl --location 'https://{
"confluenceAppKey": "client ID for your Confluence account",
"confluenceAppSecret": "client secret from your Confluence token",
"confluenceAccessToken": "access token created in Confluence",
"confluenceRefreshToken": "refresh token created in Confluence"
}(For Confluence Server/Data Center only) If you use basic authentication, the secret is stored in a JSON structure with the following keys: {
"username": "Confluence Server/Data Center username",
"password": "Confluence Server/Data Center password"
}(For Confluence Server/Data Center only) If you use Personal Access Token authentication, the secret is stored in a JSON structure with the following keys: {
"hostUrl": " Confluence Server/Data Center host URL",
"patToken": " Confluence token"
} | Yes |
| `version` | The version of this template that's currently supported. | `string` | No |
## Confluence (Server/Data Center) JSON schema
The following is the Confluence (Server/Data Center) JSON schema:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["CONFLUENCEV2", "CONFLUENCE"]
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"sslCertificatePath": {
"type": "object",
"properties": {
"bucket": {
"type": "string",
"pattern": "^[a-z0-9][\\.\\-a-z0-9]{1,61}[a-z0-9]$",
"minLength": 3,
"maxLength": 63
},
"key": {
"type": "string",
"minLength": 1,
"maxLength": 10240
}
},
"required": ["bucket", "key"]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"hostUrl": {
"type": "string",
"pattern": "https:.*"
},
"type": {
"type": "string",
"enum": ["ON_PREM"]
},
"authType": {
"type": "string",
"enum": ["Basic", "OAuth2", "Personal-token"]
}
},
"required": ["hostUrl", "type", "authType"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"space": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"page": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"blog": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"fieldForUserId": {
"type": "string"
},
"inclusionSpaceKeyFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionSpaceKeyFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"pageTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"blogTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"commentTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"attachmentTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"isCrawlPersonalSpace": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlArchivedSpace": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlArchivedPage": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlPage": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlBlog": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlPageComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlPageAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlBlogComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlBlogAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionUrlPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionUrlPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"type",
"syncMode",
"secretArn",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
## Confluence (Server/Data Center) JSON schema example
The following is the Confluence (Server/Data Center) JSON schema example:
```
{
"type": "CONFLUENCEV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-confluence-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"hostUrl": "https://mycompany.atlassian.net",
"type": "ON_PREM",
"authType": "OAuth2"
}
},
"repositoryConfigurations": {
"space": {
"fieldMappings": [
{
"indexFieldName": "space_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"page": {
"fieldMappings": [
{
"indexFieldName": "page_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"blog": {
"fieldMappings": [
{
"indexFieldName": "blog_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"isCrawlAcl": "true",
"fieldForUserId": "user_id",
"inclusionSpaceKeyFilter": ["SPACE1", "SPACE2"],
"exclusionSpaceKeyFilter": ["SPACE3"],
"pageTitleRegEX": ["^.*$"],
"blogTitleRegEX": ["^.*$"],
"commentTitleRegEX": ["^.*$"],
"attachmentTitleRegEX": ["^.*$"],
"isCrawlPersonalSpace": "false",
"isCrawlArchivedSpace": "false",
"isCrawlArchivedPage": "true",
"isCrawlPage": "true",
"isCrawlBlog": "true",
"isCrawlPageComment": "false",
"isCrawlPageAttachment": "false",
"isCrawlBlogComment": "true",
"isCrawlBlogAttachment": "true",
"maxFileSizeInMegaBytes": "50",
"inclusionFileTypePatterns": ["*.pdf", "*.docx"],
"exclusionFileTypePatterns": ["*.tmp"],
"inclusionUrlPatterns": ["*"],
"exclusionUrlPatterns": ["*.tmp"],
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
```
# Connecting Amazon Q Business to Confluence (Server/Data Center) using AWS CloudFormation
Using the CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
**Topics**
+ [
## Confluence (Server/Data Center) configuration properties
](#confluence-server-configuration-keys)
+ [
## Confluence (Server/Data Center) JSON schema for using the configuration property with AWS CloudFormation
](#confluence-server-cfn-json)
+ [
## Confluence (Server/Data Center) YAML schema for using the configuration property with AWS CloudFormation
](#confluence-server-cfn-yaml)
## Confluence (Server/Data Center) configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has the following sub-property: `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-properties: `hostUrl`, `type`, and `authType`. | Yes |
| `hostUrl` | The URL for your Confluence instance. For example, https://example.confluence.com. If you change or update your Confluence (Server/Data Center) data source URL, you also need to update your Secrets Manager secret to ensure a secure connection. | `string` Specify the URL in the pattern `https://*` | Yes |
| `type` | The hosting method for your Confluence instance. | `string` The allowed values are `SAAS` or `ON_PREM`. | Yes |
| `authType` | The authentication method for your Confluence instance. | `string` The allowed values are `Basic`, `OAuth2`, or `Personal-token`. | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties: `space`, `page`, `blog`, `comment`, and `attachment`. | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-server-cfn.html) | A list of objects that map the attributes or field names of your Confluence spaces, pages, blogs, comments, and attachments to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-server-cfn.html) | No |
| `indexFieldName` | The field name of your Confluence spaces, pages, blogs, comments, or attachments. | `string` | Yes |
| `indexFieldType` | The field type of your Confluence spaces, pages, blogs, comments, or attachments. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your Confluence spaces, pages, blogs, comments, or attachments. | `string` | Yes |
| `dateFieldFormat` | The date format of your Confluence spaces, pages, blogs, comments, or attachments. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-server-cfn.html) | Yes |
| `isCrawlAcl` | Specify true to crawl access control information from documents. Amazon Q Business crawls ACL information to ensure responses are generated only from documents your end users have access to by default. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. | `boolean` | No |
| `isRotateSecret` | Specify true if you want to automatically rotate the secret. | `boolean` | No |
| `fieldForUserId` | Specify field to use for UserId for ACL crawling. | `string` | No |
| `proxyHost` | The host where the web proxy is required. The host name should be without protocol (http:// or https://). | `string` | No |
| `proxyPort` | Port used by the host URL transport protocol. The port number should be a numeric value between 0 and 65535. | `string` | No |
| `maxFileSizeInMegaBytes` | Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-server-cfn.html) | A list of regular expression patterns to include and/or exclude certain files in your Confluence data source. Files that match the patterns are included in the index. Files that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence and the file isn't included in the index. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-server-cfn.html) | `true` to index files in your Confluence personal spaces, pages, blogs, page comments, page attachments, blog comments, and blog attachments. | `boolean` | No |
| `type` | The type of data source. We recommend that you use CONFLUENCEV2 as your data source type. | `string` The allowed values are `CONFLUENCEV2` and `CONFLUENCE`. | Yes |
| `enableIdentityCrawler` | `true` to activate identity crawler. Identity crawler is activated by default. Amazon Q Business crawls identity information from your data source to ensure responses are generated only from documents end users have access to by default. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). | `boolean` | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` Valid values are `FORCED_FULL_CRAWL` and `FULL_CRAWL`. You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/confluence-server-cfn.html) | Yes |
| `secretARN` | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains the key-value pairs required to connect to your Confluence instance. | `string` If you use OAuth 2.0 authentication, the secret must contain a JSON structure with the following keys: {
"confluenceAppKey": "client ID for your Confluence account",
"confluenceAppSecret": "client secret from your Confluence token",
"confluenceAccessToken": "access token created in Confluence",
"confluenceRefreshToken": "refresh token created in Confluence"
}(For Confluence Server/Data Center only) If you use basic authentication, the secret is stored in a JSON structure with the following keys: {
"username": "Confluence Server/Data Center username",
"password": "Confluence Server/Data Center password"
}(For Confluence Server/Data Center only) If you use Personal Access Token authentication, the secret is stored in a JSON structure with the following keys: {
"hostUrl": " Confluence Server/Data Center host URL",
"patToken": " Confluence token"
} | Yes |
| `version` | The version of this template that's currently supported. | `string` | No |
## Confluence (Server/Data Center) JSON schema for using the configuration property with AWS CloudFormation
Confluence (Server/Data Center) JSON schema
The following is the Confluence (Server/Data Center) JSON schema and examples for the configuration property for AWS CloudFormation.
**Topics**
+ [
### Confluence (Server/Data Center) JSON schema for using the configuration property with AWS CloudFormation
](#confluence-server-cfn-json-schema)
+ [
### Confluence (Server/Data Center) JSON schema example for using the configuration property with AWS CloudFormation
](#confluence-server-cfn-json-example)
### Confluence (Server/Data Center) JSON schema for using the configuration property with AWS CloudFormation
Confluence (Server/Data Center) JSON schema
The following is the Confluence (Server/Data Center) JSON schema for the configuration property for CloudFormation
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["CONFLUENCEV2", "CONFLUENCE"]
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"sslCertificatePath": {
"type": "object",
"properties": {
"bucket": {
"type": "string",
"pattern": "^[a-z0-9][\\.\\-a-z0-9]{1,61}[a-z0-9]$",
"minLength": 3,
"maxLength": 63
},
"key": {
"type": "string",
"minLength": 1,
"maxLength": 10240
}
},
"required": ["bucket", "key"]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"hostUrl": {
"type": "string",
"pattern": "https:.*"
},
"type": {
"type": "string",
"enum": ["ON_PREM"]
},
"authType": {
"type": "string",
"enum": ["Basic", "OAuth2", "Personal-token"]
}
},
"required": ["hostUrl", "type", "authType"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"space": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"page": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"blog": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"fieldForUserId": {
"type": "string"
},
"inclusionSpaceKeyFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionSpaceKeyFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"pageTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"blogTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"commentTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"attachmentTitleRegEX": {
"type": "array",
"items": {
"type": "string"
}
},
"isCrawlPersonalSpace": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlArchivedSpace": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlArchivedPage": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlPage": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlBlog": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlPageComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlPageAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlBlogComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlBlogAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionUrlPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionUrlPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"type",
"syncMode",
"secretArn",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
### Confluence (Server/Data Center) JSON schema example for using the configuration property with AWS CloudFormation
Confluence (Server/Data Center) JSON schema example
The following is the Confluence (Server/Data Center) JSON schema example for the configuration property for CloudFormation
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "CloudFormation CONFLUENCE Data Source Template",
"Resources": {
"DataSourceConfluence": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": "app12345-1234-1234-1234-123456789012",
"IndexId": "indx1234-1234-1234-1234-123456789012",
"DisplayName": "MyConfluenceDataSource",
"RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role",
"Configuration": {
"type": "CONFLUENCEV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-confluence-secret",
"enableIdentityCrawler": "true",
"sslCertificatePath": {
"bucket": "my-confluence-bucket",
"key": "path/to/certificate.pem"
},
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"hostUrl": "https://mycompany.atlassian.net",
"type": "ON_PREM",
"authType": "Personal-token"
}
},
"repositoryConfigurations": {
"space": {
"fieldMappings": [
{
"indexFieldName": "space_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"page": {
"fieldMappings": [
{
"indexFieldName": "page_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"blog": {
"fieldMappings": [
{
"indexFieldName": "blog_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"isCrawlAcl": "true",
"fieldForUserId": "user_id",
"inclusionSpaceKeyFilter": ["SPACE1", "SPACE2"],
"exclusionSpaceKeyFilter": ["SPACE3"],
"pageTitleRegEX": ["^.*$"],
"blogTitleRegEX": ["^.*$"],
"commentTitleRegEX": ["^.*$"],
"attachmentTitleRegEX": ["^.*$"],
"isCrawlPersonalSpace": "false",
"isCrawlArchivedSpace": "false",
"isCrawlArchivedPage": "true",
"isCrawlPage": "true",
"isCrawlBlog": "true",
"isCrawlPageComment": "false",
"isCrawlPageAttachment": "false",
"isCrawlBlogComment": "true",
"isCrawlBlogAttachment": "true",
"maxFileSizeInMegaBytes": "50",
"inclusionFileTypePatterns": ["*.pdf", "*.docx"],
"exclusionFileTypePatterns": ["*.tmp"],
"inclusionUrlPatterns": ["*"],
"exclusionUrlPatterns": ["*.tmp"],
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
}
}
}
}
```
## Confluence (Server/Data Center) YAML schema for using the configuration property with AWS CloudFormation
Confluence (Server/Data Center) YAML schema
The following is the Confluence (Server/Data Center) YAML schema and examples for the configuration property for AWS CloudFormation:
**Topics**
+ [
### Confluence (Server/Data Center) YAML schema for using the configuration property with AWS CloudFormation
](#confluence-server-cfn-yaml-schema)
+ [
### Confluence (Server/Data Center) YAML schema example for using the configuration property with AWS CloudFormation
](#confluence-server-cfn-yaml-example)
### Confluence (Server/Data Center) YAML schema for using the configuration property with AWS CloudFormation
Confluence (Server/Data Center) YAML schema
The following is the Confluence (Server/Data Center) YAML schema for the configuration property for CloudFormation.
```
AWSTemplateFormatVersion: "2010-09-09"
Description: CloudFormation CONFLUENCE Data Source Template
Resources:
DataSourceConfluence:
Type: AWS::QBusiness::DataSource
Properties:
ApplicationId: app12345-1234-1234-1234-123456789012
IndexId: indx1234-1234-1234-1234-123456789012
DisplayName: MyConfluenceDataSource
RoleArn: arn:aws:iam::123456789012:role/qbusiness-data-source-role
Configuration:
type: CONFLUENCEV2
syncMode: FULL_CRAWL
secretArn: arn:aws:secretsmanager:us-west-2:123456789012:secret:my-confluence-secret
enableIdentityCrawler: "true"
sslCertificatePath:
bucket: my-confluence-bucket
key: path/to/certificate.pem
connectionConfiguration:
repositoryEndpointMetadata:
hostUrl: https://mycompany.atlassian.net
type: ON_PREM
authType: Personal-token
repositoryConfigurations:
space:
fieldMappings:
- indexFieldName: space_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
page:
fieldMappings:
- indexFieldName: page_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
blog:
fieldMappings:
- indexFieldName: blog_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
comment:
fieldMappings:
- indexFieldName: comment_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
attachment:
fieldMappings:
- indexFieldName: attachment_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
additionalProperties:
isCrawlAcl: "true"
fieldForUserId: user_id
inclusionSpaceKeyFilter:
- SPACE1
- SPACE2
exclusionSpaceKeyFilter:
- SPACE3
pageTitleRegEX:
- "^.*$"
blogTitleRegEX:
- "^.*$"
commentTitleRegEX:
- "^.*$"
attachmentTitleRegEX:
- "^.*$"
isCrawlPersonalSpace: "false"
isCrawlArchivedSpace: "false"
isCrawlArchivedPage: "true"
isCrawlPage: "true"
isCrawlBlog: "true"
isCrawlPageComment: "false"
isCrawlPageAttachment: "false"
isCrawlBlogComment: "true"
isCrawlBlogAttachment: "true"
maxFileSizeInMegaBytes: "50"
inclusionFileTypePatterns:
- "*.pdf"
- "*.docx"
exclusionFileTypePatterns:
- "*.tmp"
inclusionUrlPatterns:
- "*"
exclusionUrlPatterns:
- "*.tmp"
enableDeletionProtection: "false"
deletionProtectionThreshold: "15"
```
### Confluence (Server/Data Center) YAML schema example for using the configuration property with AWS CloudFormation
Confluence (Server/Data Center) JSON schema example
The following is the Confluence (Server/Data Center) YAML example for the Configuration property for CloudFormation:
```
AWSTemplateFormatVersion: "2010-09-09"
Description: CloudFormation CONFLUENCE Data Source Template
Resources:
DataSourceConfluence:
Type: AWS::QBusiness::DataSource
Properties:
ApplicationId: app12345-1234-1234-1234-123456789012
IndexId: indx1234-1234-1234-1234-123456789012
DisplayName: MyConfluenceDataSource
RoleArn: arn:aws:iam::123456789012:role/qbusiness-data-source-role
Configuration:
type: CONFLUENCEV2
syncMode: FULL_CRAWL
secretArn: arn:aws:secretsmanager:us-west-2:123456789012:secret:my-confluence-secret
enableIdentityCrawler: "true"
sslCertificatePath:
bucket: my-confluence-bucket
key: path/to/certificate.pem
connectionConfiguration:
repositoryEndpointMetadata:
hostUrl: https://mycompany.atlassian.net
type: ON_PREM
authType: Personal-token
repositoryConfigurations:
space:
fieldMappings:
- indexFieldName: space_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
page:
fieldMappings:
- indexFieldName: page_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
blog:
fieldMappings:
- indexFieldName: blog_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
comment:
fieldMappings:
- indexFieldName: comment_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
attachment:
fieldMappings:
- indexFieldName: attachment_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
additionalProperties:
isCrawlAcl: "true"
fieldForUserId: user_id
inclusionSpaceKeyFilter:
- SPACE1
- SPACE2
exclusionSpaceKeyFilter:
- SPACE3
pageTitleRegEX:
- "^.*$"
blogTitleRegEX:
- "^.*$"
commentTitleRegEX:
- "^.*$"
attachmentTitleRegEX:
- "^.*$"
isCrawlPersonalSpace: "false"
isCrawlArchivedSpace: "false"
isCrawlArchivedPage: "true"
isCrawlPage: "true"
isCrawlBlog: "true"
isCrawlPageComment: "false"
isCrawlPageAttachment: "false"
isCrawlBlogComment: "true"
isCrawlBlogAttachment: "true"
maxFileSizeInMegaBytes: "50"
inclusionFileTypePatterns:
- "*.pdf"
- "*.docx"
exclusionFileTypePatterns:
- "*.tmp"
inclusionUrlPatterns:
- "*"
exclusionUrlPatterns:
- "*.tmp"
enableDeletionProtection: "false"
deletionProtectionThreshold: "15"
```
# How Amazon Q Business connector crawls Confluence (Server/Data Center) ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect a Confluence (Server/Data Center) data source to Amazon Q Business, Amazon Q crawls ACL information attached to a document (user and group information) from your Confluence (Server/Data Center) instance. If you choose to activate ACL crawling, the information can be used to filter chat responses based on your end users' document access level.
The connector crawls the following Confluence resources:
+ **Spaces** – A collection of related pages, blogs, and attachments. Space permissions apply to all documents in the space by default.
+ **Pages** – Documents in a space where users create and manage content. Pages can contain text, images, tables, and multimedia elements, and can have nested pages. Each page is considered a single document. Pages can be restricted to specific users and groups in the space. A nested page inherits restrictions from the parent page, and can have its own restrictions.
+ **Blogs** – Content similar to pages, typically used for updates or announcements. Each blog post is considered as a single document. Blogs can be restricted to specific users and groups in the space.
+ **Comments** – Feedback and discussions on pages or blog post content. Comments are visible to viewers of the page or post.
+ **Attachments** – Files uploaded to pages or blog posts, such as images and documents.
The connector also crawls user principal information (local user alias, local group and federated group identity configurations) and its permissions for each configured space. The Confluence (Server/Data Center) connector does not support crawling macros, whiteboards, or databases.
The connector updates ACL changes each time it crawls your data source content. To ensure that the correct users have access to the correct content, regularly re-sync your data source to capture any ACL updates.
You configure user and group access to spaces using the space permissions page. For pages and blogs, you use the restrictions page. For more information about space permissions, see [Space Permissions Overview](https://confluence.atlassian.com/doc/space-permissions-overview-139521.html) on the Confluence Support website. For more information about page and blog restrictions, see [ Page Restrictions ](https://confluence.atlassian.com/doc/page-restrictions-139414.html) on the Confluence Support website.
**Important**
For user context filtering to work correctly, users' visibility must be set to **Anyone**. For more information, see [Set your email visibility](https://support.atlassian.com/confluence-cloud/docs/configure-user-email-visibility/) in Atlassian Developer Documentation.
The group and user IDs are mapped as follows:
+ `_group_ids` – Group names are present on spaces, pages, and blogs where there are restrictions. They're mapped from the name of the group in Confluence . Group names are always lower case.
+ `_user_id` – User names are present on the space, page, or blog where there are restrictions. They're mapped depending on the type of Confluence instance that you are using.
+ For Confluence (Server/Data Center) – The `_user_id` is the user key of the user.
**Important**
To maintain secure access control for Amazon Q Business, each user must have a unique email address across all connected data sources.
In Confluence Data Center users can share an email address while having a different application-specific unique identifier. However, in Amazon Q Business email addresses act as unique identifiers.
This means that if a document is shared with a particular user (for example, arnav\$1desai@example.com who is part of pentesters@example.com) on the basis of an application-specific unique ID, every other user who shares pentesters@example.com (for example, xiulan\$1wang@example.com and efua\$1owusu@example.com, both of whom are part of pentesters@example.com) can receive Amazon Q Business responses with content from a document that was shared only with Arnav. Similarly, content created by Arnav that only he should be able to access via Amazon Q Business chat responses, could also be part of Amazon Q Business chat responses for Xiulan and Efua, because they share the same email address.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Amazon Q Business Confluence (Server/Data Center) data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application environment and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes-types.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Confluence connector supports the following entities and the associated reserved and custom attributes.
**Important**
If you map any Confluence (Server/Data Center) field to Amazon Q document title and document body fields, Amazon Q will generate responses from data in the document title and body.
**Topics**
+ [
## Space
](#confluence-field-mappings-space)
+ [
## Page
](#confluence-field-mappings-page)
+ [
## Blog
](#confluence-field-mappings-blog)
+ [
## Comment
](#confluence-field-mappings-comment)
+ [
## Attachment
](#confluence-field-mappings-attachment)
## Space
| Confluence field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| spaceName | cf\$1sp\$1document\$1title | Custom | String |
| itemType | \$1category | Default | String |
| url | \$1source\$1uri | Default | String |
| spaceKey | cf\$1space\$1key | Custom | String |
| description | cf\$1description | Custom | String |
| spaceType | cf\$1type | Custom | String |
## Page
| Confluence field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | \$1cf\$1page\$1document\$1title | Custom | String |
| authors | \$1authors | Default | String list |
| createdDate | \$1created\$1at | Default | Date |
| modifiedDate | \$1last\$1updated\$1at | Default | Date |
| labels | cf\$1labels | Custom | String list |
| version | cf\$1version | Custom | Long (numeric) |
| itemType | \$1category | Default | String |
| spaceKey | cf\$1space\$1key | Custom | String |
| spaceName | cf\$1space\$1name | Custom | String |
| url | \$1source\$1uri | Default | String |
| status | cf\$1status | Custom | String |
| parentId | cf\$1parent\$1id | Custom | String |
## Blog
| Confluence field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | cf\$1bg\$1document\$1title | Custom | String |
| author | \$1authors | Default | String list |
| publishedDate | \$1created\$1at | Default | Date |
| labels | \$1source\$1uri | Default | String |
| version | cf\$1version | Custom | Long (numeric) |
| itemType | \$1category | Custom | String |
| spaceKey | cf\$1space\$1key | Custom | String |
| modifiedDate | \$1last\$1updated\$1at | Default | Date |
| spaceName | cf\$1space\$1name | Custom | String |
| status | cf\$1status | Custom | String |
| url | \$1source\$1uri | Default | String |
| parentId | cf\$1parent\$1id | Custom | String |
## Comment
| Confluence field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | cf\$1cmt\$1document\$1title | Custom | String |
| author | \$1authors | Default | String list |
| createdDate | \$1created\$1at | Default | Date |
| version | cf\$1version | Custom | Long (numeric) |
| itemType | \$1category | Default | String |
| spaceKey | cf\$1space\$1key | Custom | String |
| spaceName | cf\$1space\$1name | Custom | String |
| contentType | cf\$1content\$1type | Custom | String |
| url | \$1source\$1uri | Default | String |
| parentId | cf\$1parent\$1id | Custom | String |
| status | cf\$1status | Custom | String |
## Attachment
| Confluence field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| fileName | cf\$1attachment\$1document\$1title | Custom | String |
| author | \$1authors | Default | String list |
| createdDate | \$1created\$1at | Default | Date |
| labels | cf\$1labels | Custom | String list |
| version | cf\$1version | Custom | Long (numeric) |
| itemType | \$1category | Default | String |
| spaceKey | cf\$1space\$1key | Custom | String |
| contentType | cf\$1content\$1type | Custom | String |
| modifiedDate | \$1last\$1updated\$1at | Default | Date |
| fileSize | cf\$1file\$1size | Custom | Long (numeric) |
| fileType | cf\$1attachment\$1file\$1type | Custom | String |
| spaceName | cf\$1space\$1name | Custom | String |
| documentId | \$1document\$1id | Default | String list |
| url | \$1source\$1uri | Default | String |
| parentId | cf\$1parent\$1id | Custom | String |
| attachmentComment | cf\$1attachment\$1comment | Custom | String |
| status | cf\$1status | Custom | String |
# IAM role for Amazon Q Confluence (Server/Data Center) connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Understand error codes in the Amazon Q Business Confluence (Server/Data Center) connector
Error Codes
The following table provides information about error codes you may see for the Confluence (Server/Data Center) connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| CNF-5500 | Null/empty username. | Provide username. |
| CNF-5501 | Error validating credentials due to Invalid username or password. | Provide valid username/password |
| CNF-5502 | Null/empty confluence AppKey. | Provide confluence AppKey. |
| CNF-5503 | Null/empty confluence Secret. | Provide confluence Secret. |
| CNF-5504 | Null/empty Client Access Token. | Provide Client Access Token. |
| CNF-5505 | Null/empty Client Refresh Token | Provide Client Refresh Token |
| CNF-5506 | Incorrect auth type. | Auth type should be Basic or OAuth2 or Personal-token. |
| CNF-5507 | Null/empty auth type. | Auth Type should not be null or empty value. |
| CNF-5508 | Empty/null host URL. | Host Url should not be null or empty value. |
| CNF-5509 | Null/empty crawl type. | Crawl Type should not be null or empty value. |
| CNF-5510 | Null/empty Repository Configurations. | Repository Configurations should not be null or empty value. |
| CNF-5511 | Incorrect type. | type should be SAAS or ON\$1PREM. |
| CNF-5512 | Invalid inclusion file type patterns. | Provide the correct inclusion patterns. |
| CNF-5513 | Invalid exclusion file type patterns. | Provide the correct exclusion patterns. |
| CNF-5514 | Invalid regex patterns. | Provide the correct regex patterns. |
| CNF-5515 | Error validating credentials due to invalid username or password. | Provide valid username and password. |
| CNF-5516 | Error validating credentials due to invalid client id or client secret. | Provide valid client id and client secret. |
| CNF-5517 | Error validating crawl type. | Provide valid crawl type. |
| CNF-5518 | Invalid URI. | Provide valid URI. |
| CNF-5519 | Null/empty DataSourceFieldName in Space Entity. | Provide value for DataSourceFieldName in Space Entity. |
| CNF-5520 | Null/empty IndexFieldName in Blog Entity. | Provide value for IndexFieldName in Blog Entity. |
| CNF-5521 | Null/empty IndexFieldType in Space Entity. | Provide value for IndexFieldType in Space Entity. |
| CNF-5522 | Null/empty password. | Provide password. |
| CNF-5523 | Incorrect auth type. | Auth type should be Basic or OAuth2. |
| CNF-5524 | Null/empty DataSourceFieldName in Page Entity. | Provide value for DataSourceFieldName in Page Entity. |
| CNF-5525 | Null/empty DataSourceFieldName in Blog Entity | Please provide value for DataSourceFieldName in Blog Entity |
| CNF-5526 | Null/empty DataSourceFieldName in Comment Entity. | Provide value for DataSourceFieldName in Comment Entity. |
| CNF-5527 | Null/empty DataSourceFieldName in Attachment Entity. | Provide value for DataSourceFieldName in Attachment Entity. |
| CNF-5528 | Null/empty IndexFieldName. | IndexFieldName field can't be null or empty value. |
| CNF-5529 | Null/empty IndexFieldName in Space Entity. | Provide value for IndexFieldName in Space Entity. |
| CNF-5530 | Null/empty IndexFieldName in Page Entity | Please provide value for IndexFieldName in Page Entity |
| CNF-5531 | Invalid isCrawlPersonalSpace value. | isCrawlPersonalSpace should be a boolean value true or false. |
| CNF-5532 | Invalid isCrawlArchivedSpace value. | isCrawlArchivedSpace should be a boolean value true or false. |
| CNF-5533 | Invalid isCrawlArchivedPage value. | isCrawlArchivedPage should be a boolean value true or false. |
| CNF-5534 | Invalid isCrawlPage value. | isCrawlPage should be a boolean value true or false. |
| CNF-5535 | Invalid isCrawlBlogComment value. | isCrawlBlogComment should be a boolean value true or false. |
| CNF-5536 | Invalid isCrawlBlogComment value. | isCrawlBlogComment should be a boolean value true or false. |
| CNF-5537 | Invalid isCrawlBlogAttachment value. | isCrawlBlogAttachment should be a boolean value true or false. |
| CNF-5538 | Error validating on protocol. | Provide valid protocol. |
| CNF-5539 | Null/empty IndexFieldName in Comment Entity. | Provide value for IndexFieldName in Comment Entity. |
| CNF-5540 | Null/empty Personal Access Token. | Provide Personal Access Token. |
| CNF-5541 | Invalid OAuth value. | Give a valid OAuth URL. |
| CNF-5542 | Invalid Space value. | Give a valid Space URL. |
| CNF-5543 | Archived Space Exception. | Check Archived Space. |
| CNF-5544 | JSON Exception for Space. | Check Space. |
| CNF-5545 | JSON Exception for Comment. | Check Comment. |
| CNF-5546 | JSON Exception for Comment. | Check Comment. |
| CNF-5547 | JSON Exception for Comment. | Check Comment. |
| CNF-5548 | JSON Exception for Attachment. | Check Attachment. |
| CNF-5549 | JSON Exception for Blog. | Check Blog. |
| CNF-5550 | JSON Exception for Page. | Check Page. |
| CNF-5551 | JSON Exception for Label. | Check Label. |
| CNF-5552 | JSON Exception for ACL. | Check ACL. |
| CNF-5553 | JSON Exception for Groups. | Check Groups. |
| CNF-5554 | JSON Exception for Group Members. | Check Group Members. |
| CNF-5555 | JSON Exception for Space Group. | Check Space Group. |
| CNF-5556 | Exception in CommentItem. | Check the CommentItem class. |
| CNF-5557 | Invalid isCrawlPageComment value. | isCrawlPageComment should be a boolean value true or false. |
| CNF-5558 | Invalid isCrawlPageAttachment value. | isCrawlPageAttachment should be a boolean value true or false. |
| CNF-5559 | Null/empty Repository Configurations. | Repository Configurations should not be null or empty value. |
| CNF-5560 | Null/empty IndexFieldName in Attachment. | Please provide value for IndexFieldName in Attachment Entity. |
| CNF-5561 | Invalid proxy url. | Proxy url should not contain http: or https. |
| CNF-5562 | Null/Empty proxy port. | Provide a valid proxy port. |
| CNF-5563 | Invalid Host URL. | Provide valid Host URL. |
| CNF-5564 | Invalid proxy port value. | Provide a valid proxy port. |
| CNF-5565 | Confluence server not reachable. | Provide a valid proxy and server details. |
| CNF-5566 | Null/empty IndexFieldType in Page Entity. | Provide value for IndexFieldType in Page Entity. |
| CNF-5567 | Null/empty IndexFieldType in Blog Entity. | Provide value for IndexFieldType in Blog Entity. |
| CNF-5568 | Null/empty IndexFieldType in Comment Entity. | Provide value for IndexFieldType in Comment Entity. |
| CNF-5569 | Null/empty IndexFieldType in Attachment. | Provide value for IndexFieldType in Attachment. Entity |
| CNF-5570 | JSON Exception for Content Ancestors. | Check your Ancestors. |
| CNF-5571 | Invalid Host URL Pattern. | Provide valid Host URL Pattern. |
| CNF-5572 | Error validating credentials due to Invalid access or refresh token. | Invalid AccessToken/RefreshToken. |
# Connecting Dropbox to Amazon Q Business
Dropbox
Dropbox is a file hosting service that offers cloud storage, document organization, and document templating services. You can connect Dropbox instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# Known limitations for the Dropbox connector
](dropbox-limitations.md)
+ [
# Dropbox connector overview
](dropbox-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Dropbox
](dropbox-prereqs.md)
+ [
# Connecting Amazon Q Business to Dropbox using the console
](dropbox-console.md)
+ [
# Connecting Amazon Q Business to Dropbox using APIs
](dropbix-api.md)
+ [
# How Amazon Q Business connector crawls Dropbox ACLs
](dropbox-user-management.md)
+ [
# Dropbox data source connector field mappings
](dropbox-field-mappings.md)
+ [
# IAM role for Dropbox connector
](dropbox-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Dropbox connector
Known limitations
The Dropbox connector has the following known limitations:
+ When Access Control Lists (ACLs) are enabled, the "Sync only new or modified content" option is not available due to Dropbox API limitations. We recommend using "Full sync" or "New, modified, or deleted content sync" modes instead, or disable ACLs if you need to use this sync mode.
# Dropbox connector overview
Overview
The following table gives an overview of the Amazon Q Business Dropbox connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/dropbox-overview.html)
# Prerequisites for connecting Amazon Q Business to Dropbox
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Dropbox, make sure you have:**
+ Created a Dropbox Advanced account and set up an admin user.
+ Created a Dropbox app with a unique **App name**, activated **Scoped Access**. For more information, see [Dropbox documentation on creating an app](https://www.dropbox.com/developers/reference/getting-started#app%20console) on the Dropbox website.
+ Activated **Full Dropbox** permissions on the Dropbox console and added the following permissions:
+ `files.content.read`
+ `files.metadata.read`
+ `sharing.read`
+ `file_requests.read`
+ `groups.read`
+ `team_info.read`
+ `team_data.content.read`
+ `account_info.read`
+ `members.read`
+ `team_data.member`
+ Create an authorization URL containing client ID (app-key), redirect\$1uri, response type, access type and scopes. Obtain User Authorization by signing in to Dropbox and grant your application the requested permissions.
`Sample Authorization URL:`
`https://www.dropbox.com/oauth2/authorize`
`?client_id=abcd1234example`
`&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback`
`&response_type=code`
`&token_access_type=offline`
`&scope=files.metadata.read%20files.content.read`
+ Exchange authorization code for tokens by requesting tokens from the Dropbox token endpoint.
+ curl https://api.dropboxapi.com/oauth2/token -d code=AUTH\$1CODE -d grant\$1type=authorization\$1code -d client\$1id=APP\$1KEY -d client\$1secret=APP\$1SECRET
+ Replace AUTH\$1CODE with the obtained authorization code, APP\$1KEY and APP\$1SECRET with your application client ID (App key) and secret key.
+ Noted your Dropbox app key, Dropbox app secret, and Dropbox access token and refresh token for OAuth 2.0 authentication credentials.
+ Generate an OAuth 2.0 access token with token\$1access\$1type=offline to obtain a short‑lived access token and a long‑lived refresh token. For more information, see [Dropbox documentation on OAuth authentication](https://developers.dropbox.com/oauth-guide) on the Dropbox website.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Dropbox authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Dropbox using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Dropbox using the AWS Management Console.
**Connecting Amazon Q to Dropbox**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Dropbox** data source to your Amazon Q application.
1. Then, on the **Dropbox** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. In **Authentication** – OAuth 2.0 (offline access) is supported. You must provide App key, App secret, access token, and refresh token.
1. In **Authentication credentials**, for **AWS Secrets Manager secret** – Choose an existing secret or create a Secrets Manager secret to store your Dropbox authentication credentials. If you choose to create a secret, an AWS Secrets Manager secret window opens.
1. Enter following information in the **Create an AWS Secrets Manager secret window**:
1. **Secret name** – A name for your secret.
1. For **App key**, **App secret**, **access token** and **refresh token** – Enter the authentication credential values that you generated from your Dropbox account.
1. Choose **Save**.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **Identity crawler** – Amazon Q crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/dropbox-connector.html#dropbox-iam).
1. In **Sync scope**, enter the following information.
1. For **Select entities or content types** – Choose entities or content types you want to crawl.
1. **Change log mode** – Choose to update your index instead of syncing all files.
1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB.
1. In **Additional configuration – *optional***, for **Regex patterns** – Add regular expression patterns to include or exclude certain files.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Dropbox using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
## Dropbox JSON schema
The following is the Dropbox JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
}
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"file": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"STRING_LIST",
"LONG",
"DATE"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "dd-MM-yyyy HH:mm:ss"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
},
"paper": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"STRING_LIST",
"LONG",
"DATE"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "dd-MM-yyyy HH:mm:ss"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
},
"papert": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"STRING_LIST",
"LONG",
"DATE"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "dd-MM-yyyy HH:mm:ss"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
},
"shortcut": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"STRING_LIST",
"LONG",
"DATE"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "dd-MM-yyyy HH:mm:ss"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
}
}
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"type": "boolean"
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"type": "boolean"
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"inclusionPatterns": {
"type": "array"
},
"exclusionPatterns": {
"type": "array"
},
"crawlFile": {
"type": "boolean"
},
"crawlPaper": {
"type": "boolean"
},
"crawlPapert": {
"type": "boolean"
},
"crawlShortcut": {
"type": "boolean"
}
}
},
"type": {
"type": "string",
"pattern": "DROPBOX"
},
"syncMode": {
"type": "string",
"enum": [
"FULL_CRAWL",
"FORCED_FULL_CRAWL",
"CHANGE_LOG"
]
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"additionalProperties": false,
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties",
"syncMode",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | The endpoint information for the data source. This data source doesn't specify an endpoint in repositoryEndpointMetadata. Rather, the connection information is included in an AWS Secrets Manager secret that you provide the secretArn. |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/dropbix-api.html) | A list of objects that map the attributes or field names of your Dropbox files, Dropbox Paper, and shortcuts to Amazon Q index field names. |
| enableIdentityCrawler | Specify true to use the Amazon Q identity crawler to sync identity/principal information on users and groups with access to specific documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). |
| secretARN | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Dropbox. The secret must contain a JSON structure with the following keys: {
"appKey": "Dropbox app key",
"appSecret": "Dropbox app secret",
"accesstoken": "access token (short live)",
"refreshtoken": "refresh token (offline-access)"
} |
| additionalProperties | Additional configuration options for your content in your data source. |
| maxFileSizeInMegaBytes | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. |
| isCrawlAcl | Specify true to crawl access control information from documents. Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. |
| fieldForUserId | Specify field to use for UserId for ACL crawling. |
| inclusionFileTypePatterns | A list of regular expression patterns to include specific file types in your Dropbox data source. Files that match the patterns are included in the index. Files that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence and the file isn't included in the index. |
| exclusionFileTypePatterns | A list of regular expression patterns to exclude specific file types in your Dropbox data source. Files that match the patterns are excluded from the index. Files that don't match the patterns are included in the index. If a file matches both an exclusion and inclusion pattern, the exclusion pattern takes precedence and the file isn't included in the index. |
| exclusionFileNamePatterns | A list of regular expression patterns to exclude specific file names in your Dropbox data source. Files that match the patterns are excluded from the index. Files that don't match the patterns are included in the index. If a file matches both an exclusion and inclusion pattern, the exclusion pattern takes precedence and the file isn't included in the index. |
| exclusionFileNamePatterns | A list of regular expression patterns to exclude specific file names in your Dropbox data source. Files that match the patterns are excluded from the index. Files that don't match the patterns are included in the index. If a file matches both an exclusion and inclusion pattern, the exclusion pattern takes precedence and the file isn't included in the index. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/dropbix-api.html) | true to index files in your Dropbox, Dropbox Paper documents, Dropbox Paper templates, and webpage shortcuts stored in your Dropbox. |
| type | The type of data source. Specify DROPBOX as your data source type. |
| useChangeLog | true to use the Dropbox change log to determine which documents require adding, updating, or deleting in the index. Depending on the change log's size, it may take longer for Amazon Q to use the change log than to scan all of your documents in your Dropbox. |
| version | The version of this template that's currently supported. |
# How Amazon Q Business connector crawls Dropbox ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an Dropbox data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your Dropbox instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
The group and user IDs are mapped as follows:
+ `_group_ids` – Group IDs exist in Dropbox on files where there are set access permissions. They're mapped from the names of the groups in Dropbox.
+ `_user_id` – User IDs exist in Dropbox on files where there are set access permissions. They're mapped from the user emails as the IDs in Dropbox.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
# Dropbox data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Dropbox connector supports the following entities and the associated reserved and custom attributes.
**Topics**
+ [
## Files
](#dropbox-field-mappings-files)
+ [
## Dropbox Paper
](#dropbox-field-mappings-paper)
+ [
## Dropbox Paper Templates
](#dropbox-field-mappings-paper-templates)
+ [
## Shortcuts
](#dropbox-field-mappings-shortcuts)
## Files
| Dropbox field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| sourceUrl | \$1source\$1uri | Default | String |
| category | \$1category | Default | String |
| fileName | dbx\$1file\$1name | Custom | String |
| fileId | dbx\$1id1 | Custom | String |
| clientModifiedDate | dbx\$1client\$1modified | Custom | Date |
| serverModifiedDate | dbx\$1server\$1modified | Custom | Date |
| fileSize | dbx\$1file\$1size | Custom | Long (numeric) |
| pathDisplay | dbx\$1path\$1display | Custom | String |
| tags | dbx\$1tags | Custom | String |
## Dropbox Paper
| Dropbox field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| sourceUrl | \$1source\$1uri | Default | String |
| category | \$1category | Default | String |
| fileName | dbx\$1file\$1name | Custom | String |
| fileId | dbx\$1id1 | Custom | String |
| clientModifiedDate | dbx\$1client\$1modified | Custom | Date |
| serverModifiedDate | dbx\$1server\$1modified | Custom | Date |
| fileSize | dbx\$1file\$1size | Custom | Long (numeric) |
| pathDisplay | dbx\$1path\$1display | Custom | String |
| tags | dbx\$1tags | Custom | String |
## Dropbox Paper Templates
| Dropbox field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| sourceUrl | \$1source\$1uri | Default | String |
| category | \$1category | Default | String |
| fileName | dbx\$1file\$1name | Custom | String |
| fileId | dbx\$1id1 | Custom | String |
| clientModifiedDate | dbx\$1client\$1modified | Custom | Date |
| serverModifiedDate | dbx\$1server\$1modified | Custom | Date |
| fileSize | dbx\$1file\$1size | Custom | Long (numeric) |
| pathDisplay | dbx\$1path\$1display | Custom | String |
| tags | dbx\$1tags | Custom | String |
## Shortcuts
| Dropbox field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| sourceUrl | \$1source\$1uri | Default | String |
| category | \$1category | Default | String |
| fileName | dbx\$1file\$1name | Custom | String |
| fileId | dbx\$1id1 | Custom | String |
| clientModifiedDate | dbx\$1client\$1modified | Custom | Date |
| serverModifiedDate | dbx\$1server\$1modified | Custom | Date |
| fileSize | dbx\$1file\$1size | Custom | Long (numeric) |
| pathDisplay | dbx\$1path\$1display | Custom | String |
| tags | dbx\$1tags | Custom | String |
# IAM role for Dropbox connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Amazon FSx (Windows) to Amazon Q Business
Amazon FSx (Windows)
Amazon FSx (Windows) is a fully managed, cloud based file server system that offers shared storage capabilities. You can connect your Amazon FSx (Windows) instance to Amazon Q Business—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
The Amazon Q Amazon FSx (Windows) data source connector supports only Amazon FSx for Windows.
**Topics**
+ [
# Amazon FSx (Windows) connector overview
](fsx-windows-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Amazon FSx (Windows)
](fsx-windows-prereqs.md)
+ [
# Connecting Amazon Q Business to Amazon FSx (Windows) using the console
](fsx-windows-console.md)
+ [
# Connecting Amazon Q Business to Amazon FSx (Windows) using APIs
](fsx-api.md)
+ [
# How Amazon Q Business connector crawls Amazon FSx (Windows) ACLs
](fsx-user-management.md)
+ [
# Amazon FSx (Windows) data source connector field mappings
](fsx-field-mappings.md)
+ [
# IAM role for Amazon FSx (Windows) connector
](fsx-windows-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Amazon FSx (Windows) connector overview
Overview
The following table gives an overview of the Amazon FSx (Windows) connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/fsx-windows-overview.html)
# Prerequisites for connecting Amazon Q Business to Amazon FSx (Windows)
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Amazon FSx (Windows), make sure you have:**
+ An Amazon FSx (Windows) account with read and mounting permissions.
+ Noted your Amazon FSx authentication credentials for an Active Directory user account. This includes your Active Directory username and your Domain Name System (DNS) domain name. For example, *user@corp.example.com*.
+ Copied your Amazon FSx file system ID.
+ Used an Amazon VPC (AWS VPC) where your Amazon FSx resides.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Amazon FSx (Windows) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
You must also make sure you have configured your Amazon VPC instance with a NAT Gateway. For instructions on how to do this, see Step 1 of [Connecting to a database in a VPC.](https://docs.aws.amazon.com/kendra/latest/dg/vpc-example.html#vpc-example-1)
# Connecting Amazon Q Business to Amazon FSx (Windows) using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Amazon FSx (Windows) using the AWS Management Console.
**Connecting Amazon Q to Amazon FSx (Windows)**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Amazon FSx (Windows)** data source to your Amazon Q application.
1. Then, on the **Amazon FSx (Windows)** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, for **Amazon FSx file system ID**—Select your file system ID or create a new directory.
Only already created file system IDs are displayed and available to connect.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name**—A name for your secret.
1. For **User name**—Enter the username for Amazon FSx Active Directory account.
1. For **Password**—Enter the password for the Amazon FSx Active Directory account.
1. Choose **Save**.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **Identity crawler** – Amazon Q crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/fsx-windows-connector.html#fsx-windows-iam).
1. In **Sync scope**, enter the following information:
1. **Regex patterns**—Add regular expression patterns to include or exclude certain content. You can add up to 100 patterns.
1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Amazon FSx (Windows) using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
## Amazon FSx JSON schema
The following is the Amazon FSx JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"fileSystemId": {
"type": "string",
"pattern": "fs-.*"
},
"fileSystemType": {
"type": "string",
"pattern": "WINDOWS"
}
},
"required": ["fileSystemId", "fileSystemType"]
}
}
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"All": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
},
"required": ["All"]
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"type": "boolean"
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"exclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": []
},
"enableIdentityCrawler": {
"type": "boolean"
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL"
]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"type" : {
"type" : "string",
"pattern": "FSX"
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"secretArn",
"enableIdentityCrawler",
"additionalProperties",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | The endpoint information for the data source. |
| fileSystemId | The identifier of the Amazon FSx (Windows) file system. You can find your file system ID on the File Systems dashboard in the Amazon FSx (Windows) console. |
| fileSystemType | The type of Amazon FSx you use: Amazon FSx (Windows) file system. |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/fsx-api.html) | A list of objects that map the attributes or field names of your Amazon FSx (Windows) pages and assets to Amazon Q index field names. |
| additionalProperties | Additional configuration options for your content in your data source. |
| isCrawlAcl | Specify true to crawl access control information from documents. Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. |
| maxFileSizeInMegaBytes | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/fsx-api.html) | A list of regular expression patterns to include specific content from you Amazon FSx (Windows) data source. Content that match the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/fsx-api.html) | A list of regular expression patterns to exclude specific content from your Amazon FSx (Windows) data source. Content that match the patterns are excluded from the index. Content that doesn't match the patterns are included in the index. If content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. |
| enableIdentityCrawler | true to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/fsx-api.html) |
| type | The type of data source. Specify FSX as your data source type. |
| version | The version of this template that's currently supported. |
# How Amazon Q Business connector crawls Amazon FSx (Windows) ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an Amazon FSx (Windows) data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from the directory service of the Amazon FSx instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
The group and user IDs are mapped as follows:
+ `_group_ids`—Group IDs exist in Amazon FSx on files where there are set access permissions. They are mapped from the system group names in the directory service of Amazon FSx.
+ `_user_id`—User IDs exist in Amazon FSx on files where there are set access permissions. They are mapped from the system user names in the directory service of Amazon FSx.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Amazon FSx (Windows) data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Amazon FSx (Windows) connector supports the following entities and the associated reserved and custom attributes.
**Topics**
| Amazon FSx (Windows) field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| creationTime | \$1created\$1at | Default | Date |
| lastModified | \$1last\$1updated\$1at | Default | Date |
| fileType | \$1file\$1type | Default | String |
| path | \$1source\$1uri | Default | String |
| author | \$1authors | Default | String list |
| size | fsx\$1size | Custom | String |
| lastAccessTime | \$1last\$1accessed\$1at | Custom | Date |
# IAM role for Amazon FSx (Windows) connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting GitHub (Cloud) to Amazon Q Business
GitHub (Cloud)
GitHub (Cloud) is a web-based hosting service for software development providing code storage and management services with version control. You can connect your GitHub (Cloud) instance to Amazon Q Business—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# GitHub (Cloud) connector overview
](github-cloud-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to GitHub (Cloud)
](github-cloud-prereqs.md)
+ [
# Connecting Amazon Q Business to GitHub (Cloud) using the console
](github-cloud-console.md)
+ [
# Connecting Amazon Q Business to GitHub (Cloud) using APIs
](github-cloud-api.md)
+ [
# Connecting Amazon Q Business to GitHub (Cloud) using AWS CloudFormation
](github-cloud-cfn.md)
+ [
# How Amazon Q Business connector crawls GitHub Cloud ACLs
](github-cloud-user-management.md)
+ [
# GitHub (Cloud) data source connector field mappings
](github-cloud-field-mappings.md)
+ [
# IAM role for GitHub (Cloud) connector
](github-cloud-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# GitHub (Cloud) connector overview
Overview
The following table gives an overview of the Amazon Q Business GitHub (Cloud) connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-overview.html)
# Prerequisites for connecting Amazon Q Business to GitHub (Cloud)
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In GitHub (Cloud), make sure you have:**
+ Created a GitHub (Cloud) user with administrative permissions to the GitHub (Cloud) organization.
+ Created a classic personal access token for authentication credentials. See [GitHub (Cloud) documentation on creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).
+ **Recommended:** Created an OAuth token for authentication credentials. Use OAuth token for better API throttle limits and connector performance. See [GitHub (Cloud) documentation on OAuth authorization](https://docs.github.com/en/rest/apps/oauth-applications?apiVersion=2022-11-28#about-oauth-apps-and-oauth-authorizations-of-github-apps).
Then, added the following OAuth scopes:
+ `repo:status` – Grants read/write access to commit statuses in public and private repositories. This scope is only necessary to grant other users or services access to private repository commit statuses without granting access to the code.
+ `repo_deployment` – Grants access to deployment statuses for public and private repositories. This scope is only necessary to grant other users or services access to deployment statuses, without granting access to the code.
+ `public_repo` – Limits access to public repositories. That includes read/write access to code, commit statuses, repository projects, collaborators, and deployment statuses for public repositories and organizations. Also required for starring public repositories.
+ `repo:invite` – Grants accept/decline abilities for invitations to collaborate on a repository. This scope is only necessary to grant other users or services access to invites without granting access to the code.
+ `security_events` – Grants: read and write access to security events in the code scanning API. This scope is only necessary to grant other users or services access to security events without granting access to the code.
+ `read:org` – Read-only access to organization membership, organization projects, and team membership.
+ `user:email` – Grants read access to a user's email addresses. Required by Amazon Q Business to crawl ACLs.
+ `user:follow` – Grants access to follow or unfollow other users. Required by Amazon Q Business to crawl ACLs.
+ `read:user` – Grants access to read a user's profile data. Required by Amazon Q Business to crawl ACLs.
+ `workflow` – Grants the ability to add and update GitHub (Cloud) Actions workflow files. Workflow files can be committed without this scope if the same file (with both the same path and contents) exists on another branch in the same repository.
For more information, see [Scopes for OAuth apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) in GitHub (Cloud) Docs.
+ Noted the GitHub (Cloud) host URL for the type of GitHub (Cloud) service that you use. For example, the host URL for GitHub (Cloud) Cloud could be *https://api.github.com*.
+ Noted the name of your organization for GitHub (Cloud) the GitHub (Cloud) Enterprise account you want to connect to. You can find your organization name by logging into GitHub (Cloud) desktop and selecting **Your organizations** under your profile picture dropdown.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your GitHub (Cloud) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
**Note**
For more information on connecting GitHub (Cloud) to Amazon Q Business, see [Connect the Amazon Q Business generative AI coding companion to your GitHub repositories with Amazon Q GitHub (Cloud) connector](https://aws.amazon.com/blogs/machine-learning/connect-the-amazon-q-business-generative-ai-coding-companion-to-your-github-repositories-with-amazon-q-github-cloud-connector/) in the *AWS Machine Learning Blog*.
# Connecting Amazon Q Business to GitHub (Cloud) using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to GitHub (Cloud) using the AWS Management Console.
**Connecting Amazon Q to GitHub (Cloud)**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **GitHub** data source to your Amazon Q application.
1. Then, on the **GitHub (Cloud)** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. **Source** – Choose your GitHub (Cloud) source details.
1. **GitHub (Cloud) source** – Choose GitHub (Cloud) Enterprise Cloud.
1. **GitHub (Cloud) host URL** – Enter the GitHub (Cloud) host name with the protocol (http:// or https://). For example: *https://api.github.com*.
1. **GitHub (Cloud) organization name** – You can find your organization name when you log in to GitHub (Cloud) desktop and go to **Your organizations** under your profile picture dropdown.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. **GitHub (Cloud) token** – Enter the access token you created in GitHub (Cloud).
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-connector.html#github-cloud-iam).
1. In **Sync scope**, enter the following information:
1. **Select repositories to crawl**—Select between crawling **All** repositories or **Select repositories**.
If you choose **Select repositories**, add names for the repositories in **Name of repository** and, optionally, the name of any specific branches in **Name of branch**.
1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB.
1. **Additional configuration – *optional*** – Configure the following settings:
+ **Content types** – Select the file types you want to include. You can choose from the following options: **All**, **Files**, **Issues**, **Issue comments**, **Issue comment attachments**, **Pull request comment attachments**, **Pull requests**, and **Pull request comments**.
+ **Regex patterns** – Regular expression patterns to include or exclude certain files. You can add up to 100 patterns.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to GitHub (Cloud) using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
**Topics**
+ [
## GitHub (Cloud) configuration properties
](#github-cloud-configuration-keys)
+ [
## GitHub (Cloud) JSON schema
](#github-cloud-json)
+ [
## GitHub (Cloud) JSON schema example
](#s3-api-json-example)
## GitHub (Cloud) configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has a sub-property called `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-api.html) | Yes |
| `hostUrl` | The GitHub (Cloud) host URL. For example, if you use GitHub (Cloud) Enterprise Cloud: https://api.github.com. | `string` | Yes |
| `type` | The hosting method for your GitHub instance. | `string` The only allowed value is `SAAS`. | Yes |
| `organizationName` | You can find your organization name when you log in to GitHub (Cloud) desktop and go to Your organizations under your profile picture dropdown. | `string` | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `array` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-api.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-api.html) | A list of objects that map the attributes or field names of your GitHub (Cloud) pages and assets to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-api.html) | No |
| `indexFieldName` | The field name of your GitHub (Cloud) pages and assets. | `string` | Yes |
| `indexFieldType` | The field type of your GitHub (Cloud) pages and assets. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your GitHub (Cloud) pages and assets. | `string` | Yes |
| `dateFieldFormat` | The date format of your GitHub (Cloud) pages and assets. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-api.html) | Yes |
| `isCrawlAcl` | Specify true to crawl access control information from documents. | `boolean` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` The allowed values are numbers between greater than 0 and less than or equal to 50. | No |
| `fieldForUserId` | Specify field to use for UserId for ACL crawling. | `string` | No |
| repositoryFilter | A list of names of the specific repositories and branch names you want to index. | `object` This property has the following sub-properties: `repositoryName` and `branchNameList`. | No |
| `repositoryName` | The list of repository names that you want to index. | `string` | No |
| `branchNameList` | The list of branch names that you want to index. | `array (string)` | No |
| `crawlRepository` | Specify true to crawl repositories. | `boolean` | No |
| `crawlRepositoryDocuments` | Specify true to crawl repository documents. | `boolean` | No |
| `crawlIssue` | Specify true to crawl issues. | `boolean` | No |
| `crawlIssueComment` | Specify true to crawl issue comments. | `boolean` | No |
| `crawlIssueCommentAttachment` | Specify true to crawl issue comment attachments. | `boolean` | No |
| `crawlPullRequest` | Specify true to crawl pull requests. | `boolean` | No |
| `crawlPullRequestComment` | Specify true to crawl pull request comments. | `boolean` | No |
| `crawlPullRequestCommentAttachment` | Specify true to crawl pull request comment attachments. | `boolean` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-api.html) | A list of regular expression patterns to include specific content in your GitHub (Cloud) data source. Content that matches the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-api.html) | A list of regular expression patterns to exclude specific content in your GitHub (Cloud) data source. Content that matches the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| `type` | The type of data source. Specify GITHUB as your data source type. | `string` | Yes |
| `enableIdentityCrawler` | Specify true to use the Amazon Q identity crawler to sync identity/principal information on users and groups with access to specific documents. | `boolean` | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-api.html) | Yes |
| `secretArn` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your GitHub (Cloud). | `string` The secret must contain a JSON structure with the following keys: {
"personalToken": "token"
} | No |
| `version` | The version of this template that's currently supported. | `string` | No |
## GitHub (Cloud) JSON schema
The following is the GitHub (Cloud) JSON schema:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"pattern": "GITHUB"
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"hostUrl": {
"type": "string",
"pattern": "https://.*"
},
"organizationName": {
"type": "string"
}
},
"required": ["type", "hostUrl", "organizationName"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"ghRepository": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghCommit": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghIssueDocument": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghIssueComment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghIssueAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghPRDocument": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghPRComment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghPRAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"crawlRepository": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlRepositoryDocuments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlIssue": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlIssueComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlIssueCommentAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPullRequest": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPullRequestComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPullRequestCommentAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"repositoryFilter": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"repositoryName": {
"type": "string"
},
"branchNameList": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
]
},
"inclusionFolderNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFolderNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"syncMode",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
## GitHub (Cloud) JSON schema example
The following is the GitHub (Cloud) JSON schema example:
```
{
"type": "GITHUB",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-github-secret",
"enableIdentityCrawler": "true",
"sslCertificatePath": {
"bucket": "my-github-bucket",
"key": "certificates/my-cert.pem"
},
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"type": "GitHub",
"hostUrl": "https://api.github.com",
"organizationName": "my-org"
}
},
"repositoryConfigurations": {
"ghRepository": {
"fieldMappings": [
{
"indexFieldName": "repo_name",
"indexFieldType": "STRING",
"dataSourceFieldName": "name",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"ghCommit": {
"fieldMappings": [
{
"indexFieldName": "commit_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"isCrawlAcl": "true",
"maxFileSizeInMegaBytes": "50",
"crawlRepository": "true",
"crawlIssue": "true",
"repositoryFilter": [
{
"repositoryName": "my-repo",
"branchNameList": ["main", "develop"]
}
],
"inclusionFileTypePatterns": ["*.md", "*.txt"],
"exclusionFileNamePatterns": ["*draft*"],
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
},
"version": "1.0.0"
}
```
# Connecting Amazon Q Business to GitHub (Cloud) using AWS CloudFormation
Using the CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
**Topics**
+ [
## GitHub (Cloud) configuration properties
](#github-cloud-configuration-keys)
+ [
## GitHub (Cloud) JSON schema for using the configuration property with AWS CloudFormation
](#github-cloud-cfn-json)
+ [
## GitHub (Cloud) YAML schema for using the configuration property with AWS CloudFormation
](#github-cloud-cfn-yaml)
## GitHub (Cloud) configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has a sub-property called `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-cfn.html) | Yes |
| `hostUrl` | The GitHub (Cloud) host URL. For example, if you use GitHub (Cloud) Enterprise Cloud: https://api.github.com. | `string` | Yes |
| `type` | The hosting method for your GitHub instance. | `string` The only allowed value is `SAAS`. | Yes |
| `organizationName` | You can find your organization name when you log in to GitHub (Cloud) desktop and go to Your organizations under your profile picture dropdown. | `string` | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `array` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-cfn.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-cfn.html) | A list of objects that map the attributes or field names of your GitHub (Cloud) pages and assets to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-cfn.html) | No |
| `indexFieldName` | The field name of your GitHub (Cloud) pages and assets. | `string` | Yes |
| `indexFieldType` | The field type of your GitHub (Cloud) pages and assets. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your GitHub (Cloud) pages and assets. | `string` | Yes |
| `dateFieldFormat` | The date format of your GitHub (Cloud) pages and assets. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-cfn.html) | Yes |
| `isCrawlAcl` | Specify true to crawl access control information from documents. | `boolean` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` The allowed values are numbers between greater than 0 and less than or equal to 50. | No |
| `fieldForUserId` | Specify field to use for UserId for ACL crawling. | `string` | No |
| repositoryFilter | A list of names of the specific repositories and branch names you want to index. | `object` This property has the following sub-properties: `repositoryName` and `branchNameList`. | No |
| `repositoryName` | The list of repository names that you want to index. | `string` | No |
| `branchNameList` | The list of branch names that you want to index. | `array (string)` | No |
| `crawlRepository` | Specify true to crawl repositories. | `boolean` | No |
| `crawlRepositoryDocuments` | Specify true to crawl repository documents. | `boolean` | No |
| `crawlIssue` | Specify true to crawl issues. | `boolean` | No |
| `crawlIssueComment` | Specify true to crawl issue comments. | `boolean` | No |
| `crawlIssueCommentAttachment` | Specify true to crawl issue comment attachments. | `boolean` | No |
| `crawlPullRequest` | Specify true to crawl pull requests. | `boolean` | No |
| `crawlPullRequestComment` | Specify true to crawl pull request comments. | `boolean` | No |
| `crawlPullRequestCommentAttachment` | Specify true to crawl pull request comment attachments. | `boolean` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-cfn.html) | A list of regular expression patterns to include specific content in your GitHub (Cloud) data source. Content that matches the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-cfn.html) | A list of regular expression patterns to exclude specific content in your GitHub (Cloud) data source. Content that matches the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| `type` | The type of data source. Specify GITHUB as your data source type. | `string` | Yes |
| `enableIdentityCrawler` | Specify true to use the Amazon Q identity crawler to sync identity/principal information on users and groups with access to specific documents. | `boolean` | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-cloud-cfn.html) | Yes |
| `secretArn` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your GitHub (Cloud). | `string` The secret must contain a JSON structure with the following keys: {
"personalToken": "token"
} | No |
| `version` | The version of this template that's currently supported. | `string` | No |
## GitHub (Cloud) JSON schema for using the configuration property with AWS CloudFormation
GitHub (Cloud) JSON schema
The following is the GitHub (Cloud) JSON schema and examples for the configuration property for AWS CloudFormation.
**Topics**
+ [
### GitHub (Cloud) JSON schema for using the configuration property with AWS CloudFormation
](#github-cloud-cfn-json-schema)
+ [
### GitHub (Cloud) JSON schema example for using the configuration property with AWS CloudFormation
](#github-cloud-cfn-json-example)
### GitHub (Cloud) JSON schema for using the configuration property with AWS CloudFormation
GitHub (Cloud) JSON schema
The following is the GitHub (Cloud) JSON schema for the configuration property for CloudFormation
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"pattern": "GITHUB"
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"hostUrl": {
"type": "string",
"pattern": "https://.*"
},
"organizationName": {
"type": "string"
}
},
"required": ["type", "hostUrl", "organizationName"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"ghRepository": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghCommit": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghIssueDocument": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghIssueComment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghIssueAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghPRDocument": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghPRComment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghPRAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"crawlRepository": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlRepositoryDocuments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlIssue": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlIssueComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlIssueCommentAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPullRequest": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPullRequestComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPullRequestCommentAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"repositoryFilter": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"repositoryName": {
"type": "string"
},
"branchNameList": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
]
},
"inclusionFolderNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFolderNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"syncMode",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
### GitHub (Cloud) JSON schema example for using the configuration property with AWS CloudFormation
GitHub (Cloud) JSON schema example
The following is the GitHub (Cloud) JSON schema example for the configuration property for CloudFormation
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "CloudFormation GITHUB Data Source Template",
"Resources": {
"DataSourceGitHub": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": "app12345-1234-1234-1234-123456789012",
"IndexId": "indx1234-1234-1234-1234-123456789012",
"DisplayName": "MyGitHubDataSource",
"RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role",
"Configuration": {
"type": "GITHUB",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-github-secret",
"enableIdentityCrawler": "true",
"sslCertificatePath": {
"bucket": "my-github-bucket",
"key": "certificates/my-cert.pem"
},
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"type": "GitHub",
"hostUrl": "https://api.github.com",
"organizationName": "my-org"
}
},
"repositoryConfigurations": {
"ghRepository": {
"fieldMappings": [
{
"indexFieldName": "repo_name",
"indexFieldType": "STRING",
"dataSourceFieldName": "name",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"ghCommit": {
"fieldMappings": [
{
"indexFieldName": "commit_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"isCrawlAcl": "true",
"maxFileSizeInMegaBytes": "50",
"crawlRepository": "true",
"crawlIssue": "true",
"repositoryFilter": [
{
"repositoryName": "my-repo",
"branchNameList": ["main", "develop"]
}
],
"inclusionFileTypePatterns": ["*.md", "*.txt"],
"exclusionFileNamePatterns": ["*draft*"],
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
}
}
}
}
```
## GitHub (Cloud) YAML schema for using the configuration property with AWS CloudFormation
GitHub (Cloud) YAML schema
The following is the GitHub (Cloud) YAML schema and examples for the configuration property for AWS CloudFormation:
**Topics**
+ [
### GitHub (Cloud) YAML schema for using the configuration property with AWS CloudFormation
](#github-cloud-cfn-yaml-schema)
+ [
### GitHub (Cloud) YAML schema example for using the configuration property with AWS CloudFormation
](#github-cloud-cfn-yaml-example)
### GitHub (Cloud) YAML schema for using the configuration property with AWS CloudFormation
GitHub (Cloud) YAML schema
The following is the GitHub (Cloud) YAML schema for the configuration property for CloudFormation.
```
type: object
properties:
type:
type: string
pattern: GITHUB
syncMode:
type: string
enum:
- FULL_CRAWL
- FORCED_FULL_CRAWL
- CHANGE_LOG
secretArn:
type: string
minLength: 20
maxLength: 2048
enableIdentityCrawler:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
connectionConfiguration:
type: object
properties:
repositoryEndpointMetadata:
type: object
properties:
type:
type: string
hostUrl:
type: string
pattern: "https://.*"
organizationName:
type: string
required:
- type
- hostUrl
- organizationName
required:
- repositoryEndpointMetadata
repositoryConfigurations:
type: object
properties:
ghRepository:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
ghCommit:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
ghIssueDocument:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
ghIssueComment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
ghIssueAttachment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
ghPRDocument:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
ghPRComment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
ghPRAttachment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
additionalProperties:
type: object
properties:
isCrawlAcl:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
maxFileSizeInMegaBytes:
type: string
fieldForUserId:
type: string
crawlRepository:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlRepositoryDocuments:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlIssue:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlIssueComment:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlIssueCommentAttachment:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlPullRequest:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlPullRequestComment:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlPullRequestCommentAttachment:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
repositoryFilter:
type: array
items:
type: object
properties:
repositoryName:
type: string
branchNameList:
type: array
items:
type: string
inclusionFolderNamePatterns:
type: array
items:
type: string
inclusionFileTypePatterns:
type: array
items:
type: string
inclusionFileNamePatterns:
type: array
items:
type: string
exclusionFolderNamePatterns:
type: array
items:
type: string
exclusionFileTypePatterns:
type: array
items:
type: string
exclusionFileNamePatterns:
type: array
items:
type: string
enableDeletionProtection:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
default: false
deletionProtectionThreshold:
type: string
default: "15"
required: []
version:
type: string
anyOf:
- pattern: 1.0.0
required:
- syncMode
- enableIdentityCrawler
- connectionConfiguration
- repositoryConfigurations
- additionalProperties
```
### GitHub (Cloud) YAML schema example for using the configuration property with AWS CloudFormation
GitHub (Cloud) JSON schema example
The following is the GitHub (Cloud) YAML example for the Configuration property for CloudFormation:
```
AWSTemplateFormatVersion: "2010-09-09"
Description: CloudFormation GITHUB Data Source Template
Resources:
DataSourceGitHub:
Type: AWS::QBusiness::DataSource
Properties:
ApplicationId: app12345-1234-1234-1234-123456789012
IndexId: indx1234-1234-1234-1234-123456789012
DisplayName: MyGitHubDataSource
RoleArn: arn:aws:iam::123456789012:role/qbusiness-data-source-role
Configuration:
type: GITHUB
syncMode: FULL_CRAWL
secretArn: arn:aws:secretsmanager:us-west-2:123456789012:secret:my-github-secret
enableIdentityCrawler: "true"
sslCertificatePath:
bucket: my-github-bucket
key: certificates/my-cert.pem
connectionConfiguration:
repositoryEndpointMetadata:
type: GitHub
hostUrl: https://api.github.com
organizationName: my-org
repositoryConfigurations:
ghRepository:
fieldMappings:
- indexFieldName: repo_name
indexFieldType: STRING
dataSourceFieldName: name
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
ghCommit:
fieldMappings:
- indexFieldName: commit_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
additionalProperties:
isCrawlAcl: "true"
maxFileSizeInMegaBytes: "50"
crawlRepository: "true"
crawlIssue: "true"
repositoryFilter:
- repositoryName: my-repo
branchNameList:
- main
- develop
inclusionFileTypePatterns:
- "*.md"
- "*.txt"
exclusionFileNamePatterns:
- "*draft*"
enableDeletionProtection: "false"
deletionProtectionThreshold: "15"
```
# How Amazon Q Business connector crawls GitHub Cloud ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an GitHub Cloud data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your GitHub instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
GitHub Cloud's structure consists of repositories, teams, and projects. When you connect a GitHub Cloud data source to Amazon Q Business, it crawls GitHub Cloud repositories as defnied by your configuration, but it does not support teams or projects, meaning data related to team structures, internal communications, and project management is not retrieved. The child entities of repositories like Issues, Pull Requests, Files, and Comments are crawled.
When you connect an GitHub Cloud data source to Amazon Q Business, Amazon Q Business makes a copy of these resources and creates an index that can be used to respond to user prompts and queries. Additionally, Amazon Q crawls ACL information attached to a document (user and group information) from your GitHub Cloud instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
**Roles/permissions**: GitHub Cloud has three roles:
+ >Members - Default. Users with configurable repository and project permissions
+ Owners - Users with full administrative control. There should be at least two for continuity.
+ Outside Collaborators - Users who have restricted access to private repositories with managed permissions
The GitHub Cloud connector translates these roles into Amazon Q Business compatible ACLs, supporting View (Read), Edit, and Delete permissions. Since the lowest permission level is Read, more granular permissions beyond this do not impact data synchronization.
**Identity Crawling**: The connector supports both individual user and group synchronization. For Users, it maps repository-specific members and outside collaborators based on usernames, enforcing assigned GitHub Cloud permissions in Amazon Q. For Groups, it treats each repository as a group and members as organization group members. The connector retrieves ACL information for shared users based on repository name.
**Permission Inheritance**: There are three types of repositories:
+ Public - Accessible to everyone; repositories inherit permissions from the organization.
+ Private - Limited to the owner and explicitly granted collaborators. Does not inherit permissions from a parent. However, child entities such as Issues, Pull Requests, Files, and Comments inherit permissions from their parent repositories. When specific ACLs are definted, they replace the parent ACL.
+ Internal - Accessible to all organization members but not to external users; repositories inherits permission from the organization
**Change Management**: Change Log Mode captures and logs any updates to access control lists (ACLs). When a user is removed from a private repository or deactivated, they are automatically excluded from the access list, and these changes are recorded in the change log. Change Log Mode enables incremental updates by indexing only newly added, updated, or deleted content since the last crawl, preventing unnecessary re-indexing. Any modifications to user access or permissions are also captured, ensuring accurate and up-to-date indexing of GitHub Cloud content.
**Failure handling**: The connector implements a fail-close approach, meaning that if there are permission-related issues or API failures, the document is skipped from ingestion rather than being made publicly accessible.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# GitHub (Cloud) data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application environment and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes-types.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q GitHub (Cloud) connector supports the following entities and the associated reserved and custom attributes.
**Important**
If you map any GitHub (Cloud) field to Amazon Q document title and document body fields, Amazon Q will generate responses from data in the document title and body.
**Note**
You can map any GitHub (Cloud) field to the document title or document body Amazon Q reserved/default index fields.
**Topics**
+ [
## Repository
](#github-field-mappings-repository)
+ [
## Repository Commit
](#github-field-mappings-repository-commit)
+ [
## Issue Document
](#github-field-mappings-issue-document)
+ [
## Issue Comment
](#github-field-mappings-issue-comment)
+ [
## Issue Attachment
](#github-field-mappings-issue-attachment)
+ [
## Pull Request Comment
](#github-field-mappings-pull-request-comment)
+ [
## Pull Request Document
](#github-field-mappings-pull-request-document)
+ [
## Pull Request Attachment
](#github-field-mappings-pull-request-attachment)
## Repository
| GitHub (Cloud) field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| Description | \$1document\$1body | Default | String |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| owner | \$1authors | Default | String list |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
## Repository Commit
| GitHub (Cloud) field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| Description | \$1document\$1body | Default | String |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| fileType | \$1file\$1type | Default | String |
| owner | \$1authors | Default | String list |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| fileName | gh\$1file\$1name | Default | String |
| fileSize | gh\$1size | Default | Long (numeric) |
| branchName | gh\$1branch\$1name | Default | String |
## Issue Document
| GitHub (Cloud) field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| issueNumber | gh\$1issue\$1number | Custom | Long (numeric) |
| issueTitle | gh\$1issue\$1title | Custom | String |
| owner | \$1authors | Default | String list |
| fileType | \$1file\$1type | Default | String |
| issueSourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| issueFileName | gh\$1file\$1name | Custom | String |
| issueState | gh\$1issue\$1state | Custom | String |
| issueLabel | gh\$1issue\$1labels | Default | String list |
| issueAssignee | gh\$1issue\$1assignee | Default | String list |
## Issue Comment
| GitHub (Cloud) field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| issueNumber | gh\$1issue\$1number | Custom | Long (numeric) |
| issueTitle | gh\$1issue\$1title | Custom | String |
| owner | \$1authors | Default | String list |
| issueSourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| issueState | gh\$1issue\$1state | Custom | String |
| issueLabel | gh\$1issue\$1labels | Default | String list |
| issueAssignee | gh\$1issue\$1assignee | Default | String list |
## Issue Attachment
| GitHub (Cloud) field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| issueNumber | gh\$1issue\$1number | Custom | Long (numeric) |
| issueTitle | gh\$1issue\$1title | Custom | String |
| owner | \$1authors | Default | String list |
| issueSourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| issueFileName | gh\$1file\$1name | Custom | String |
| issueFileType | \$1file\$1type | Custom | String |
| issueState | gh\$1issue\$1state | Custom | String |
| issueLabel | gh\$1issue\$1labels | Default | String list |
| issueAssignee | gh\$1issue\$1assignee | Default | String list |
## Pull Request Comment
| GitHub (Cloud) field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| PRNumber | gh\$1pr\$1number | Custom | Long (numeric) |
| PRTitle | gh\$1pr\$1title | Custom | String |
| owner | \$1authors | Default | String list |
| PRSourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| PRState | gh\$1pr\$1state | Custom | String |
| PRLabel | gh\$1pr\$1labels | Default | String list |
| PRAssignee | gh\$1pr\$1assignee | Default | String list |
## Pull Request Document
| GitHub (Cloud) field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| PRNumber | gh\$1number | Custom | Long (numeric) |
| PRTitle | gh\$1pr\$1title | Custom | String |
| owner | \$1authors | Default | String list |
| PRSourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| PRFileName | gh\$1file\$1name | Custom | String |
| PRFileType | \$1file\$1type | Custom | String |
| PRState | gh\$1pr\$1state | Custom | String |
| PRLabel | gh\$1pr\$1labels | Default | String list |
| PRAssignee | gh\$1pr\$1assignee | Default | String list |
## Pull Request Attachment
| GitHub (Cloud) field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| PRNumber | gh\$1number | Custom | Long (numeric) |
| PRTitle | gh\$1pr\$1title | Custom | String |
| owner | \$1authors | Default | String list |
| PRSourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| PRFileName | gh\$1file\$1name | Custom | String |
| PRFileType | \$1file\$1type | Custom | String |
| PRState | gh\$1pr\$1state | Custom | String |
| PRLabel | gh\$1pr\$1labels | Default | String list |
| PRAssignee | gh\$1pr\$1assignee | Default | String list |
# IAM role for GitHub (Cloud) connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting GitHub (Server) to Amazon Q Business
GitHub (Server)
GitHub (Server) is a web-based hosting service for software development providing code storage and management services with version control. You can connect your GitHub (Server) instance to Amazon Q Business—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# GitHub (Server) connector overview
](github-server-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to GitHub (Server)
](github-server-prereqs.md)
+ [
# Connecting Amazon Q Business to GitHub (Server) using the console
](github-server-console.md)
+ [
# Connecting Amazon Q Business to GitHub (Server) using APIs
](github-server-api.md)
+ [
# Connecting Amazon Q Business to GitHub (Server) using AWS CloudFormation
](github-server-cfn.md)
+ [
# How Amazon Q Business connector crawls GitHub Server ACLs
](github-server-user-management.md)
+ [
# GitHub (Server) data source connector field mappings
](github-server-field-mappings.md)
+ [
# IAM role for GitHub (Server) connector
](github-server-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# GitHub (Server) connector overview
Overview
The following table gives an overview of the Amazon Q Business GitHub (Server) connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-overview.html)
# Prerequisites for connecting Amazon Q Business to GitHub (Server)
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In GitHub (Server), make sure you have:**
+ Created a GitHub (Server) user with administrative permissions to the GitHub (Server) organization.
+ Created a classic personal access token for authentication credentials. See [GitHub documentation on creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).
+ **Recommended:**Created an OAuth token for authentication credentials. Use OAuth token for better API throttle limits and connector performance. See [GitHub documentation on OAuth authorization](https://docs.github.com/en/rest/apps/oauth-applications?apiVersion=2022-11-28#about-oauth-apps-and-oauth-authorizations-of-github-apps).
Then, added the following OAuth scopes:
+ `repo:status` – Grants read/write access to commit statuses in public and private repositories. This scope is only necessary to grant other users or services access to private repository commit statuses without granting access to the code.
+ `repo_deployment` – Grants access to deployment statuses for public and private repositories. This scope is only necessary to grant other users or services access to deployment statuses, without granting access to the code.
+ `public_repo` – Limits access to public repositories. That includes read/write access to code, commit statuses, repository projects, collaborators, and deployment statuses for public repositories and organizations. Also required for starring public repositories.
+ `repo:invite` – Grants accept/decline abilities for invitations to collaborate on a repository. This scope is only necessary to grant other users or services access to invites without granting access to the code.
+ `security_events` – Grants: read and write access to security events in the code scanning API. This scope is only necessary to grant other users or services access to security events without granting access to the code.
+ `read:org` – Read-only access to organization membership, organization projects, and team membership.
+ `user:email` – Grants read access to a user's email addresses. Required by Amazon Q Business to crawl ACLs.
+ `user:follow` – Grants access to follow or unfollow other users. Required by Amazon Q Business to crawl ACLs.
+ `read:user` – Grants access to read a user's profile data. Required by Amazon Q Business to crawl ACLs.
+ `workflow` – Grants the ability to add and update GitHub (Server) Actions workflow files. Workflow files can be committed without this scope if the same file (with both the same path and contents) exists on another branch in the same repository.
For more information, see [Scopes for OAuth apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) in GitHub (Server) Docs.
+ Noted the GitHub (Server) host URL for the type of GitHub (Server) service that you use. For example, the host URL for GitHub (Server) Server could be *https://on-prem-host-url/api/v3/*.
+ Noted the name of your organization for GitHub (Server) the GitHub Enterprise account you want to connect to. You can find your organization name by logging into GitHub (Server) desktop and selecting **Your organizations** under your profile picture dropdown.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your GitHub (Server) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to GitHub (Server) using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to GitHub (Server) using the AWS Management Console.
**Connecting Amazon Q to GitHub (Server)**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **GitHub** data source to your Amazon Q application.
1. Then, on the **GitHub (Server)** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. **Source** – Choose your GitHub (Server) source details.
1. **GitHub (Server) source** – Choose GitHub (Server) Enterprise Cloud.
1. **GitHub (Server) host URL** – Enter the GitHub (Server) host name with the protocol (http:// or https://). For example: *https://on-prem-host-url/api/v3/*.
1. **GitHub (Server) organization name** – You can find your organization name when you log in to GitHub (Server) desktop and go to **Your organizations** under your profile picture dropdown.
1. **SSL certificate location**— Enter the path to the SSL certificate stored in an Amazon S3 bucket. You use this to connect to Github (Server) with a secure SSL connection.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. **GitHub (Server) token** – Enter the access token you created in GitHub.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-connector.html#github-server-iam).
1. In **Sync scope**, enter the following information:
1. **Select repositories to crawl**—Select between crawling **All** repositories or **Select repositories**.
If you choose **Select repositories**, add names for the repositories in **Name of repository** and, optionally, the name of any specific branches in **Name of branch**.
1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB.
1. **Additional configuration – *optional*** – Configure the following settings:
+ **Content types** – Select the file types you want to include. You can choose from the following options: **All**, **Files**, **Issues**, **Issue comments**, **Issue comment attachments**, **Pull request comment attachments**, **Pull requests**, and **Pull request comments**.
+ **Regex patterns** – Regular expression patterns to include or exclude certain files. You can add up to 100 patterns.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to GitHub (Server) using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
**Topics**
+ [
## GitHub (Cloud) configuration properties
](#github-cloud-configuration-keys)
+ [
## GitHub (Server) JSON schema
](#github-server-json)
+ [
## GitHub (Server) JSON schema example
](#github-server-api-json-example)
## GitHub (Cloud) configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has a sub-property called `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-api.html) | Yes |
| `hostUrl` | The GitHub (Cloud) host URL. For example, if you use GitHub (Cloud) Enterprise Server: https://on-prem-host-url/api/v3/. | `string` | Yes |
| `type` | The hosting method for your GitHub instance. | `string` The only allowed value is `ON_PREMISE`. | Yes |
| `organizationName` | You can find your organization name when you log in to GitHub (Cloud) desktop and go to Your organizations under your profile picture dropdown. | `string` | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-api.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-api.html) | A list of objects that map the attributes or field names of your GitHub pages and assets to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-api.html) | No |
| `indexFieldName` | The field name of your GitHub (Cloud) pages and assets. | `string` | Yes |
| `indexFieldType` | The field type of your GitHub (Cloud) pages and assets. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your GitHub (Cloud) pages and assets. | `string` | Yes |
| `dateFieldFormat` | The date format of your GitHub (Cloud) pages and assets. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-api.html) | Yes |
| `isCrawlAcl` | Specify true to crawl access control information from documents. | `boolean` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` The allowed values are numbers between greater than 0 and less than or equal to 50. | No |
| `fieldForUserId` | Specify field to use for UserId for ACL crawling. | `string` | No |
| repositoryFilter | A list of names of the specific repositories and branch names you want to index. | `object` This property has the following sub-properties: `repositoryName` and `branchNameList`. | No |
| `repositoryName` | The list of repository names that you want to index. | `string` | No |
| `branchNameList` | The list of branch names that you want to index. | `array (string)` | No |
| `crawlRepository` | Specify true to crawl repositories. | `boolean` | No |
| `crawlRepositoryDocuments` | Specify true to crawl repository documents. | `boolean` | No |
| `crawlIssue` | Specify true to crawl issues. | `boolean` | No |
| `crawlIssueComment` | Specify true to crawl issue comments. | `boolean` | No |
| `crawlIssueCommentAttachment` | Specify true to crawl issue comment attachments. | `boolean` | No |
| `crawlPullRequest` | Specify true to crawl pull requests. | `boolean` | No |
| `crawlPullRequestComment` | Specify true to crawl pull request comments. | `boolean` | No |
| `crawlPullRequestCommentAttachment` | Specify true to crawl pull request comment attachments. | `boolean` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-api.html) | A list of regular expression patterns to include specific content in your GitHub data source. Content that matches the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-api.html) | A list of regular expression patterns to exclude specific content in your GitHub data source. Content that matches the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| `type` | The type of data source. Specify GITHUB as your data source type. | `string` | Yes |
| `enableIdentityCrawler` | Specify true to use the Amazon Q identity crawler to sync identity/principal information on users and groups with access to specific documents. | `boolean` | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-api.html) | Yes |
| `secretArn` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your GitHub (Cloud). | `string` The secret must contain a JSON structure with the following keys: {
"personalToken": "token"
} | No |
| `version` | The version of this template that's currently supported. | `string` | No |
## GitHub (Server) JSON schema
The following is the GitHub (Server) JSON schema:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"pattern": "GITHUB"
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"sslCertificatePath": {
"type": "object",
"properties": {
"bucket": {
"type": "string",
"pattern": "^[a-z0-9][\\.\\-a-z0-9]{1,61}[a-z0-9]$",
"minLength": 3,
"maxLength": 63
},
"key": {
"type": "string",
"minLength": 1,
"maxLength": 10240
}
},
"required": ["bucket", "key"]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"hostUrl": {
"type": "string",
"pattern": "https://.*"
},
"organizationName": {
"type": "string"
}
},
"required": ["type", "hostUrl", "organizationName"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"ghRepository": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghCommit": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghIssueDocument": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghIssueComment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghIssueAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghPRDocument": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghPRComment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghPRAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"crawlRepository": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlRepositoryDocuments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlIssue": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlIssueComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlIssueCommentAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPullRequest": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPullRequestComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPullRequestCommentAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"repositoryFilter": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"repositoryName": {
"type": "string"
},
"branchNameList": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
]
},
"inclusionFolderNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFolderNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"syncMode",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
## GitHub (Server) JSON schema example
The following is the GitHub (Server) JSON schema example:
```
{
"type": "GITHUB",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-github-secret",
"enableIdentityCrawler": "true",
"sslCertificatePath": {
"bucket": "my-github-bucket",
"key": "certificates/my-cert.pem"
},
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"type": "GitHub",
"hostUrl": "https://host.url.com",
"organizationName": "my-org"
}
},
"repositoryConfigurations": {
"ghRepository": {
"fieldMappings": [
{
"indexFieldName": "repo_name",
"indexFieldType": "STRING",
"dataSourceFieldName": "name",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"ghCommit": {
"fieldMappings": [
{
"indexFieldName": "commit_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"isCrawlAcl": "true",
"maxFileSizeInMegaBytes": "50",
"crawlRepository": "true",
"crawlIssue": "true",
"repositoryFilter": [
{
"repositoryName": "my-repo",
"branchNameList": ["main", "develop"]
}
],
"inclusionFileTypePatterns": ["*.md", "*.txt"],
"exclusionFileNamePatterns": ["*draft*"],
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
},
"version": "1.0.0"
}
```
# Connecting Amazon Q Business to GitHub (Server) using AWS CloudFormation
Using the CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
**Topics**
+ [
## GitHub (Cloud) configuration properties
](#github-cloud-configuration-keys)
+ [
## GitHub (Server) JSON schema for using the configuration property with AWS CloudFormation
](#github-server-cfn-json)
+ [
## GitHub (Server) YAML schema for using the configuration property with AWS CloudFormation
](#github-server-cfn-yaml)
## GitHub (Cloud) configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has a sub-property called `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-cfn.html) | Yes |
| `hostUrl` | The GitHub (Cloud) host URL. For example, if you use GitHub (Cloud) Enterprise Server: https://on-prem-host-url/api/v3/. | `string` | Yes |
| `type` | The hosting method for your GitHub instance. | `string` The only allowed value is `ON_PREMISE`. | Yes |
| `organizationName` | You can find your organization name when you log in to GitHub (Cloud) desktop and go to Your organizations under your profile picture dropdown. | `string` | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-cfn.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-cfn.html) | A list of objects that map the attributes or field names of your GitHub pages and assets to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-cfn.html) | No |
| `indexFieldName` | The field name of your GitHub (Cloud) pages and assets. | `string` | Yes |
| `indexFieldType` | The field type of your GitHub (Cloud) pages and assets. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your GitHub (Cloud) pages and assets. | `string` | Yes |
| `dateFieldFormat` | The date format of your GitHub (Cloud) pages and assets. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-cfn.html) | Yes |
| `isCrawlAcl` | Specify true to crawl access control information from documents. | `boolean` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` The allowed values are numbers between greater than 0 and less than or equal to 50. | No |
| `fieldForUserId` | Specify field to use for UserId for ACL crawling. | `string` | No |
| repositoryFilter | A list of names of the specific repositories and branch names you want to index. | `object` This property has the following sub-properties: `repositoryName` and `branchNameList`. | No |
| `repositoryName` | The list of repository names that you want to index. | `string` | No |
| `branchNameList` | The list of branch names that you want to index. | `array (string)` | No |
| `crawlRepository` | Specify true to crawl repositories. | `boolean` | No |
| `crawlRepositoryDocuments` | Specify true to crawl repository documents. | `boolean` | No |
| `crawlIssue` | Specify true to crawl issues. | `boolean` | No |
| `crawlIssueComment` | Specify true to crawl issue comments. | `boolean` | No |
| `crawlIssueCommentAttachment` | Specify true to crawl issue comment attachments. | `boolean` | No |
| `crawlPullRequest` | Specify true to crawl pull requests. | `boolean` | No |
| `crawlPullRequestComment` | Specify true to crawl pull request comments. | `boolean` | No |
| `crawlPullRequestCommentAttachment` | Specify true to crawl pull request comment attachments. | `boolean` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-cfn.html) | A list of regular expression patterns to include specific content in your GitHub data source. Content that matches the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-cfn.html) | A list of regular expression patterns to exclude specific content in your GitHub data source. Content that matches the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| `type` | The type of data source. Specify GITHUB as your data source type. | `string` | Yes |
| `enableIdentityCrawler` | Specify true to use the Amazon Q identity crawler to sync identity/principal information on users and groups with access to specific documents. | `boolean` | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/github-server-cfn.html) | Yes |
| `secretArn` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your GitHub (Cloud). | `string` The secret must contain a JSON structure with the following keys: {
"personalToken": "token"
} | No |
| `version` | The version of this template that's currently supported. | `string` | No |
## GitHub (Server) JSON schema for using the configuration property with AWS CloudFormation
GitHub (Server) JSON schema
The following is the GitHub (Server) JSON schema and examples for the configuration property for AWS CloudFormation.
**Topics**
+ [
### GitHub (Server) JSON schema for using the configuration property with AWS CloudFormation
](#github-server-cfn-json-schema)
+ [
### GitHub (Server) JSON schema example for using the configuration property with AWS CloudFormation
](#github-server-cfn-json-example)
### GitHub (Server) JSON schema for using the configuration property with AWS CloudFormation
GitHub (Server) JSON schema
The following is the GitHub (Server) JSON schema for the configuration property for CloudFormation
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"pattern": "GITHUB"
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"sslCertificatePath": {
"type": "object",
"properties": {
"bucket": {
"type": "string",
"pattern": "^[a-z0-9][\\.\\-a-z0-9]{1,61}[a-z0-9]$",
"minLength": 3,
"maxLength": 63
},
"key": {
"type": "string",
"minLength": 1,
"maxLength": 10240
}
},
"required": ["bucket", "key"]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"hostUrl": {
"type": "string",
"pattern": "https://.*"
},
"organizationName": {
"type": "string"
}
},
"required": ["type", "hostUrl", "organizationName"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"ghRepository": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghCommit": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghIssueDocument": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghIssueComment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghIssueAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghPRDocument": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghPRComment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"ghPRAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"crawlRepository": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlRepositoryDocuments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlIssue": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlIssueComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlIssueCommentAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPullRequest": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPullRequestComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPullRequestCommentAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"repositoryFilter": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"repositoryName": {
"type": "string"
},
"branchNameList": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
]
},
"inclusionFolderNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFolderNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"syncMode",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
### GitHub (Server) JSON schema example for using the configuration property with AWS CloudFormation
GitHub (Server) JSON schema example
The following is the GitHub (Server) JSON schema example for the configuration property for CloudFormation
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "CloudFormation GITHUB Data Source Template",
"Resources": {
"DataSourceGitHub": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": "app12345-1234-1234-1234-123456789012",
"IndexId": "indx1234-1234-1234-1234-123456789012",
"DisplayName": "MyGitHubDataSource",
"RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role",
"Configuration": {
"type": "GITHUB",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-github-secret",
"enableIdentityCrawler": "true",
"sslCertificatePath": {
"bucket": "my-github-bucket",
"key": "certificates/my-cert.pem"
},
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"type": "GitHub",
"hostUrl": "https://host.url.com",
"organizationName": "my-org"
}
},
"repositoryConfigurations": {
"ghRepository": {
"fieldMappings": [
{
"indexFieldName": "repo_name",
"indexFieldType": "STRING",
"dataSourceFieldName": "name",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"ghCommit": {
"fieldMappings": [
{
"indexFieldName": "commit_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"isCrawlAcl": "true",
"maxFileSizeInMegaBytes": "50",
"crawlRepository": "true",
"crawlIssue": "true",
"repositoryFilter": [
{
"repositoryName": "my-repo",
"branchNameList": ["main", "develop"]
}
],
"inclusionFileTypePatterns": ["*.md", "*.txt"],
"exclusionFileNamePatterns": ["*draft*"],
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
}
}
}
}
```
## GitHub (Server) YAML schema for using the configuration property with AWS CloudFormation
GitHub (Server) YAML schema
The following is the GitHub (Server) YAML schema and examples for the configuration property for AWS CloudFormation:
**Topics**
+ [
### GitHub (Server) YAML schema for using the configuration property with AWS CloudFormation
](#github-server-cfn-yaml-schema)
+ [
### GitHub (Server) YAML schema example for using the configuration property with AWS CloudFormation
](#github-server-cfn-yaml-example)
### GitHub (Server) YAML schema for using the configuration property with AWS CloudFormation
GitHub (Server) YAML schema
The following is the GitHub (Server) YAML schema for the configuration property for CloudFormation.
```
type: object
properties:
type:
type: string
pattern: GITHUB
syncMode:
type: string
enum:
- FULL_CRAWL
- FORCED_FULL_CRAWL
- CHANGE_LOG
secretArn:
type: string
minLength: 20
maxLength: 2048
enableIdentityCrawler:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
sslCertificatePath:
type: object
properties:
bucket:
type: string
pattern: "^[a-z0-9][\\.\\-a-z0-9]{1,61}[a-z0-9]$"
minLength: 3
maxLength: 63
key:
type: string
minLength: 1
maxLength: 10240
required:
- bucket
- key
connectionConfiguration:
type: object
properties:
repositoryEndpointMetadata:
type: object
properties:
type:
type: string
hostUrl:
type: string
pattern: "https://.*"
organizationName:
type: string
required:
- type
- hostUrl
- organizationName
required:
- repositoryEndpointMetadata
repositoryConfigurations:
type: object
properties:
ghRepository:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
ghCommit:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
ghIssueDocument:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
ghIssueComment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
ghIssueAttachment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
ghPRDocument:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
ghPRComment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
ghPRAttachment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
additionalProperties:
type: object
properties:
isCrawlAcl:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
maxFileSizeInMegaBytes:
type: string
fieldForUserId:
type: string
crawlRepository:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlRepositoryDocuments:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlIssue:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlIssueComment:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlIssueCommentAttachment:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlPullRequest:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlPullRequestComment:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlPullRequestCommentAttachment:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
repositoryFilter:
type: array
items:
type: object
properties:
repositoryName:
type: string
branchNameList:
type: array
items:
type: string
inclusionFolderNamePatterns:
type: array
items:
type: string
inclusionFileTypePatterns:
type: array
items:
type: string
inclusionFileNamePatterns:
type: array
items:
type: string
exclusionFolderNamePatterns:
type: array
items:
type: string
exclusionFileTypePatterns:
type: array
items:
type: string
exclusionFileNamePatterns:
type: array
items:
type: string
enableDeletionProtection:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
default: false
deletionProtectionThreshold:
type: string
default: "15"
required: []
version:
type: string
anyOf:
- pattern: 1.0.0
required:
- syncMode
- enableIdentityCrawler
- connectionConfiguration
- repositoryConfigurations
- additionalProperties
```
### GitHub (Server) YAML schema example for using the configuration property with AWS CloudFormation
GitHub (Server) JSON schema example
The following is the GitHub (Server) YAML example for the Configuration property for CloudFormation:
```
AWSTemplateFormatVersion: "2010-09-09"
Description: CloudFormation GITHUB Data Source Template
Resources:
DataSourceGitHub:
Type: AWS::QBusiness::DataSource
Properties:
ApplicationId: app12345-1234-1234-1234-123456789012
IndexId: indx1234-1234-1234-1234-123456789012
DisplayName: MyGitHubDataSource
RoleArn: arn:aws:iam::123456789012:role/qbusiness-data-source-role
Configuration:
type: GITHUB
syncMode: FULL_CRAWL
secretArn: arn:aws:secretsmanager:us-west-2:123456789012:secret:my-github-secret
enableIdentityCrawler: "true"
sslCertificatePath:
bucket: my-github-bucket
key: certificates/my-cert.pem
connectionConfiguration:
repositoryEndpointMetadata:
type: GitHub
hostUrl: https://api.github.com
organizationName: my-org
repositoryConfigurations:
ghRepository:
fieldMappings:
- indexFieldName: repo_name
indexFieldType: STRING
dataSourceFieldName: name
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
ghCommit:
fieldMappings:
- indexFieldName: commit_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
additionalProperties:
isCrawlAcl: "true"
maxFileSizeInMegaBytes: "50"
crawlRepository: "true"
crawlIssue: "true"
repositoryFilter:
- repositoryName: my-repo
branchNameList:
- main
- develop
inclusionFileTypePatterns:
- "*.md"
- "*.txt"
exclusionFileNamePatterns:
- "*draft*"
enableDeletionProtection: "false"
deletionProtectionThreshold: "15"
```
# How Amazon Q Business connector crawls GitHub Server ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an GitHub Server data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your GitHub instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
GitHub Server's structure consists of repositories, teams, and projects. When you connect a GitHub Server data source to Amazon Q Business, it crawls GitHub Server repositories as defnied by your configuration, but it does not support teams or projects, meaning data related to team structures, internal communications, and project management is not retrieved. The child entities of repositories like Issues, Pull Requests, Files, and Comments are crawled.
When you connect an GitHub Server data source to Amazon Q Business, Amazon Q Business makes a copy of these resources and creates an index that can be used to respond to user prompts and queries. Additionally, Amazon Q crawls ACL information attached to a document (user and group information) from your GitHub Server instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
**Roles/permissions**: GitHub Server has three roles:
+ >Members - Default. Users with configurable repository and project permissions
+ Owners - Users with full administrative control. There should be at least two for continuity.
+ Outside Collaborators - Users who have restricted access to private repositories with managed permissions
The GitHub Server connector translates these roles into Amazon Q Business compatible ACLs, supporting View (Read), Edit, and Delete permissions. Since the lowest permission level is Read, more granular permissions beyond this do not impact data synchronization.
**Identity Crawling**: The connector supports both individual user and group synchronization. For Users, it maps repository-specific members and outside collaborators based on usernames, enforcing assigned GitHub Server permissions in Amazon Q. For Groups, it treats each repository as a group and members as organization group members. The connector retrieves ACL information for shared users based on repository name.
**Permission Inheritance**: There are three types of repositories:
+ Public - Accessible to everyone; repositories inherit permissions from the organization.
+ Private - Limited to the owner and explicitly granted collaborators. Does not inherit permissions from a parent. However, child entities such as Issues, Pull Requests, Files, and Comments inherit permissions from their parent repositories. When specific ACLs are definted, they replace the parent ACL.
+ Internal - Accessible to all organization members but not to external users; repositories inherits permission from the organization
**Change Management**: Change Log Mode captures and logs any updates to access control lists (ACLs). When a user is removed from a private repository or deactivated, they are automatically excluded from the access list, and these changes are recorded in the change log. Change Log Mode enables incremental updates by indexing only newly added, updated, or deleted content since the last crawl, preventing unnecessary re-indexing. Any modifications to user access or permissions are also captured, ensuring accurate and up-to-date indexing of GitHub Server content.
**Failure handling**: The connector implements a fail-close approach, meaning that if there are permission-related issues or API failures, the document is skipped from ingestion rather than being made publicly accessible.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# GitHub (Server) data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application environment and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes-types.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q GitHub connector supports the following entities and the associated reserved and custom attributes.
**Important**
If you map any GitHub (Server) field to Amazon Q document title and document body fields, Amazon Q will generate responses from data in the document title and body.
**Note**
You can map any GitHub field to the document title or document body Amazon Q reserved/default index fields.
**Topics**
+ [
## Repository
](#github-field-mappings-repository)
+ [
## Repository Commit
](#github-field-mappings-repository-commit)
+ [
## Issue Document
](#github-field-mappings-issue-document)
+ [
## Issue Comment
](#github-field-mappings-issue-comment)
+ [
## Issue Attachment
](#github-field-mappings-issue-attachment)
+ [
## Pull Request Comment
](#github-field-mappings-pull-request-comment)
+ [
## Pull Request Document
](#github-field-mappings-pull-request-document)
+ [
## Pull Request Attachment
](#github-field-mappings-pull-request-attachment)
## Repository
| GitHub field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| Description | \$1document\$1body | Default | String |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| owner | \$1authors | Default | String list |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
## Repository Commit
| GitHub field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| Description | \$1document\$1body | Default | String |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| fileType | \$1file\$1type | Default | String |
| owner | \$1authors | Default | String list |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| fileName | gh\$1file\$1name | Default | String |
| fileSize | gh\$1size | Default | Long (numeric) |
| branchName | gh\$1branch\$1name | Default | String |
## Issue Document
| GitHub field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| issueNumber | gh\$1issue\$1number | Custom | Long (numeric) |
| issueTitle | gh\$1issue\$1title | Custom | String |
| owner | \$1authors | Default | String list |
| fileType | \$1file\$1type | Default | String |
| issueSourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| issueFileName | gh\$1file\$1name | Custom | String |
| issueState | gh\$1issue\$1state | Custom | String |
| issueLabel | gh\$1issue\$1labels | Default | String list |
| issueAssignee | gh\$1issue\$1assignee | Default | String list |
## Issue Comment
| GitHub field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| issueNumber | gh\$1issue\$1number | Custom | Long (numeric) |
| issueTitle | gh\$1issue\$1title | Custom | String |
| owner | \$1authors | Default | String list |
| issueSourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| issueState | gh\$1issue\$1state | Custom | String |
| issueLabel | gh\$1issue\$1labels | Default | String list |
| issueAssignee | gh\$1issue\$1assignee | Default | String list |
## Issue Attachment
| GitHub field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| issueNumber | gh\$1issue\$1number | Custom | Long (numeric) |
| issueTitle | gh\$1issue\$1title | Custom | String |
| owner | \$1authors | Default | String list |
| issueSourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| issueFileName | gh\$1file\$1name | Custom | String |
| issueFileType | \$1file\$1type | Custom | String |
| issueState | gh\$1issue\$1state | Custom | String |
| issueLabel | gh\$1issue\$1labels | Default | String list |
| issueAssignee | gh\$1issue\$1assignee | Default | String list |
## Pull Request Comment
| GitHub field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| PRNumber | gh\$1pr\$1number | Custom | Long (numeric) |
| PRTitle | gh\$1pr\$1title | Custom | String |
| owner | \$1authors | Default | String list |
| PRSourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| PRState | gh\$1pr\$1state | Custom | String |
| PRLabel | gh\$1pr\$1labels | Default | String list |
| PRAssignee | gh\$1pr\$1assignee | Default | String list |
## Pull Request Document
| GitHub field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| PRNumber | gh\$1number | Custom | Long (numeric) |
| PRTitle | gh\$1pr\$1title | Custom | String |
| owner | \$1authors | Default | String list |
| PRSourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| PRFileName | gh\$1file\$1name | Custom | String |
| PRFileType | \$1file\$1type | Custom | String |
| PRState | gh\$1pr\$1state | Custom | String |
| PRLabel | gh\$1pr\$1labels | Default | String list |
| PRAssignee | gh\$1pr\$1assignee | Default | String list |
## Pull Request Attachment
| GitHub field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| repositoryName | gh\$1repository\$1name | Custom | String |
| repositoryVisibility | gh\$1repository\$1visibility | Custom | String |
| category | \$1category | Default | String |
| PRNumber | gh\$1number | Custom | Long (numeric) |
| PRTitle | gh\$1pr\$1title | Custom | String |
| owner | \$1authors | Default | String list |
| PRSourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| PRFileName | gh\$1file\$1name | Custom | String |
| PRFileType | \$1file\$1type | Custom | String |
| PRState | gh\$1pr\$1state | Custom | String |
| PRLabel | gh\$1pr\$1labels | Default | String list |
| PRAssignee | gh\$1pr\$1assignee | Default | String list |
# IAM role for GitHub (Server) connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Gmail to Amazon Q Business
Gmail
With Amazon Q Business, you can connect your Gmail enterprise email system to unlock valuable organizational knowledge stored in email communications. When you connect Gmail to Amazon Q Business, your users can search and get answers from email content and conversations directly through the Amazon Q web experience.
You can connect your Gmail instance to Amazon Q Business using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API. This connection enables your organization to leverage email-based knowledge for improved decision-making and faster information discovery.
**Topics**
+ [
# Gmail connector versions
](gmail-versions.md)
+ [
# Gmail connector overview
](gmail-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Gmail
](gmail-prereqs.md)
+ [
# Connecting Amazon Q Business to Gmail using the latest connector (Console)
](gmail-console-new.md)
+ [
# Connecting Amazon Q Business to Gmail using the legacy connector (Console)
](gmail-console-original.md)
+ [
# Connecting Amazon Q Business to Gmail using the new connector (API)
](gmail-new-api.md)
+ [
# Connecting Amazon Q Business to Gmail using the original connector (API)
](gmail-original-api.md)
+ [
# How Amazon Q Business connector crawls Gmail ACLs
](gmail-user-management.md)
+ [
# Gmail data source connector field mappings
](gmail-field-mappings.md)
+ [
# IAM role for Amazon Q Business Gmail connector
](gmail-iam-role.md)
+ [
# Understand error codes in the Amazon Q Business Gmail connector
](gmail-error-codes.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Gmail connector versions
Connector versions
Gmail offers two connector versions to meet different configuration needs:
## Latest Gmail connector (Recommended)
Latest connector
**Note**
The latest connector provides improved accuracy. We recommend using the latest connector for new implementations. The legacy connector remains available for customers requiring specific features not yet supported in the latest connector.
The latest Gmail connector provides a simplified configuration experience with essential features:
+ Configurable crawling of Email and Draft Email content
+ Simplified filtering with only Date Range options
+ Enhanced UI with improved validation and tips
+ Automatic crawling of ACL and identity information
## Legacy Gmail connector
Legacy connector
The original Gmail connector provides full-featured configuration with advanced options:
+ Complete entity type selection including Message attachments
+ Advanced filtering options including domains, keywords, and labels
+ Custom field mappings for metadata extraction
+ Configurable sync modes and VPC settings
+ Regex pattern matching for complex attachment filtering
+ Manual ACL and identity crawling configuration
# Gmail connector overview
Overview
The following table gives an overview of the Gmail connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/gmail-overview.html)
# Prerequisites for connecting Amazon Q Business to Gmail
Prerequisites
Before you connect Amazon Q Business to Gmail, you need to set up authentication and permissions in your Google Workspace environment. This setup ensures Amazon Q Business can securely access your email data while respecting your organization's access controls.
# Setting up Google Workspace authentication
Complete these steps in your Google Workspace environment to prepare for the Amazon Q Business connection:
**To set up Google Workspace authentication**
1. Verify you have Google Workspace (not personal Gmail accounts).
1. Create a Google Cloud Platform admin account and Google Cloud project if you don't already have them.
1. Enable the Gmail API and Admin SDK API in your Google Cloud project:
1. Go to the Google Cloud Console API Library.
1. Search for and enable the Gmail API.
1. Search for and enable the Admin SDK API.
1. Create a service account and download the JSON private key. For detailed instructions, see [Create a service account key](https://cloud.google.com/iam/docs/keys-create-delete#creating) and [Service account credentials](https://cloud.google.com/iam/docs/service-account-creds#key-types) in the Google Cloud documentation.
1. Configure OAuth scopes for your service account. Add these required scopes:
+ `https://www.googleapis.com/auth/admin.directory.user.readonly`
+ `https://www.googleapis.com/auth/admin.directory.group.readonly`
+ `https://www.googleapis.com/auth/gmail.readonly`
1. Save the following information for use in Amazon Q Business:
+ Admin account email address
+ Service account email address
+ Private key from the JSON file
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Gmail authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Gmail using the latest connector (Console)
Using the latest connector (Console)
The following procedure outlines how to connect Amazon Q Business to Gmail using the latest connector and the AWS Management Console. The latest connector provides a simplified configuration experience with automatic ACL and identity crawling.
**Connecting Amazon Q to Gmail using the latest connector**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Gmail** data source to your Amazon Q application.
1. Then, on the **Gmail** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Authentication**, for **AWS Secrets Manager secret** – Choose an existing secret or create a Secrets Manager secret to store your Gmail authentication credentials. If you choose to create a secret, an AWS Secrets Manager secret window opens.
1. Enter the following information in the **Create an AWS Secrets Manager secret window**:
1. **Secret Name** – A name for your secret.
1. **Client email** – The client email address that you copied from your Google service account. For example, it might look like this:
```
"{"clientEmailId":"service-account@123.iam.gserviceaccount.com","adminAccountEmailId":"admin@accounthost.com",
"privateKey":"-----BEGIN PRIVATE KEY-----PRIVATE KEY HERE-----END PRIVATE KEY-----\n"}"
```
1. **Admin account email** – The admin account email address that you would like to use.
1. **Private key** – The private key that you copied from your Google service account.
1. Choose **Save**.
1. For **Additional configuration – *optional***, configure the date range filter:
1. **Date range** – Configure the time period for crawling email messages. Choose from:
+ *Date range*: Specify start and end dates. **(optional)** - if not provided, the entire inbox is crawled.
+ *Start date onwards*: Specify only a start date to crawl from that date forward
**Note**
**Simplified configuration:** The latest connector automatically crawls email content and allows configurable draft email crawling. Only date range filtering is available to keep the configuration simple and reliable.
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Gmail using the legacy connector (Console)
Using the legacy connector (Console)
The following procedure outlines how to connect Amazon Q Business to Gmail using the legacy connector and the AWS Management Console. The legacy connector provides full-featured configuration with advanced options.
**Connecting Amazon Q to Gmail using the legacy connector**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Gmail** data source to your Amazon Q application.
1. Then, on the **Gmail** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. In **Authentication**, for **AWS Secrets Manager secret** – Choose an existing secret or create a Secrets Manager secret to store your Gmail authentication credentials. If you choose to create a secret, an AWS Secrets Manager secret window opens.
1. Enter the following information in the **Create an AWS Secrets Manager secret window**:
1. **Secret Name** – A name for your secret.
1. **Client email** – The client email address that you copied from your Google service account.
1. **Admin account email** – The admin account email address that you would like to use.
1. **Private key** – The private key that you copied from your Google service account.
1. Choose **Save**.
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/gmail-connector.html#gmail-iam).
1. In **Sync scope**, choose from the following entity types:
+ **Message attachments** – Choose to crawl email attachments. Messages are crawled by default.
1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB.
1. For **Additional configuration – *optional***, configure the comprehensive filtering options available in the original connector:
1. **Date range** – Enter a date range to specify the start and end date of email messages to be crawled.
1. **Email domains** – Include or exclude email messages based on domains.
1. **Keywords in subjects** – Include or exclude email messages based on keywords in their subjects.
**Note**
You can also choose to include any documents that match all the subject keywords that you have entered.
1. **Labels** – Add regular expression patterns to include or exclude specific labels. You can add up to 100 patterns.
1. **Attachments** – Add regular expression patterns to include or exclude specific attachments. You can add up to 100 patterns.
1. **Multi-media content configuration – optional** – To enable content extraction from embedded images and visuals in documents, choose **Visual content in documents**.
To extract audio transcriptions and video content, enable processing for the following file types:
1. For **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Gmail using the new connector (API)
Using the new connector (API)
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
## New Gmail connector JSON schema
The following is the new Gmail connector JSON schema:
```
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["GMAILV2"]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"secretArn": {
"type": "string",
"pattern": "^arn:[a-z0-9-\\.]{1,63}:[a-z0-9-\\.]{0,63}:[a-z0-9-\\.]{0,63}:[a-z0-9-\\.]{0,63}:[^/].{0,1023}$"
}
},
"required": ["secretArn"]
},
"dataEntityConfiguration": {
"type": "object",
"properties": {
"crawlDraftEmails": {
"type": "boolean"
}
}
},
"filterConfiguration": {
"type": "object",
"properties": {
"maxFileSizeInMegaBytes": {
"type": "string",
"pattern": "^\\d+$"
},
"startDateFilter": {
"type": "string",
"format": "date-time"
},
"endDateFilter": {
"type": "string",
"format": "date-time"
}
}
},
"deletionProtectionConfiguration": {
"type": "object",
"properties": {
"enableDeletionProtection": {
"type": "boolean"
},
"deletionProtectionThreshold": {
"type": "string",
"pattern": "^(100|[1-9][0-9]?)$"
}
},
"required": ["enableDeletionProtection", "deletionProtectionThreshold"]
}
},
"required": [
"type",
"connectionConfiguration",
"dataEntityConfiguration"
]
}
```
The following table provides information about important JSON keys to configure for the new Gmail connector.
| Configuration | Description |
| --- | --- |
| type | The type of data source. Specify GMAILV2 for the new Gmail connector. |
| connectionConfiguration | Configuration information for connecting to the Gmail data source. |
| secretArn | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains the key-value pairs required to connect to your Gmail. The secret must contain a JSON structure with the following keys: {
"adminAccountEmailId": "${adminAccountEmailId}",
"clientEmailId": "${clientEmailId}",
"privateKey": "${privateKey}"
} |
| dataEntityConfiguration | Configuration for the types of data entities to crawl. |
| crawlDraftEmails | A Boolean value to choose whether you want to crawl draft messages. Default is false. |
| filterConfiguration | Optional filtering configuration for the data source. |
| maxFileSizeInMegaBytes | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. |
| startDateFilter | Specify messages to be included from a certain start date onwards. Use ISO 8601 date-time format. |
| endDateFilter | Specify messages to be included up to a certain end date. Use ISO 8601 date-time format. |
| deletionProtectionConfiguration | Configuration for deletion protection to prevent accidental data loss. |
| enableDeletionProtection | A Boolean value to enable deletion protection. When enabled, prevents deletion of more than the specified threshold percentage of documents. |
| deletionProtectionThreshold | The maximum percentage (1-100) of documents that can be deleted in a single sync. Required when deletion protection is enabled. |
# Connecting Amazon Q Business to Gmail using the original connector (API)
Using the original connector (API)
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
## Original Gmail connector JSON schema
The following is the original Gmail connector JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
}
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"message": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"attachments": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING"]
},
"dataSourceFieldName": {
"type": "string"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
}
},
"required": []
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"type": "boolean"
},
"fieldForUserId": {
"type": "string"
},
"inclusionLabelNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionLabelNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionAttachmentTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionAttachmentTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionAttachmentNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionAttachmentNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionSubjectFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionSubjectFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"isSubjectAnd": {
"type": "boolean"
},
"inclusionFromFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFromFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionToFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionToFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionCcFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionCcFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionBccFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionBccFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"beforeDateFilter": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
},
{
"type": "string",
"pattern": ""
}
]
},
"afterDateFilter": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
},
{
"type": "string",
"pattern": ""
}
]
},
"isCrawlAttachment": {
"type": "boolean"
},
"shouldCrawlDraftMessages": {
"type": "boolean"
},
"maxFileSizeInMegaBytes": {
"type": "string"
}
},
"required": [
"isCrawlAttachment",
"shouldCrawlDraftMessages"
]
},
"type" : {
"type" : "string",
"pattern": "GMAIL"
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL"
]
},
"enableIdentityCrawler": {
"type": "boolean"
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties",
"syncMode",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. Specify the type of data source and the secret ARN. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/gmail-original-api.html) | A list of objects that map the attributes or field names of your Gmail messages and attachments to Amazon Q index field names. |
| additionalProperties | Additional configuration options for your content in your data source. |
| isCrawlAcl | Specify true to crawl access control information from documents. Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. |
| fieldForUserId | Specify field to use for UserId for ACL crawling. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/gmail-original-api.html) | A list of regular expression patterns to include or exclude messages with specific subject names in your Gmail data source. Files that match the patterns are included in the index. If a file matches both an inclusion and an exclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. |
| isSubjectAnd | true to index. |
| beforeDateFilter | Specify messages and attachments to be included before a certain date. |
| afterDateFilter | Specify messages and attachments to be included after a certain date. |
| isCrawlAttachment | A Boolean value to choose whether you want to crawl attachments. Messages are automatically crawled. |
| maxFileSizeInMegaBytes | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. |
| type | The type of data source. Specify GMAIL as your data source type. |
| shouldCrawlDraftMessages | A Boolean value to choose whether you want to crawl draft messages. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose from the following options:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/gmail-original-api.html) Because there is no API to update permanently deleted Gmail messages, a **New, modified, or deleted content sync** does *not* do the following: Remove messages that were permanently deleted from Gmail from your Amazon Q index Sync changes in Gmail email labels To sync your Gmail data source label changes and permanently deleted email messages to your Amazon Q index, you must run full crawls periodically. |
| enableIdentityCrawler | Specify true to use the Amazon Q identity crawler to sync identity/principal information on users and groups with access to specific documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). |
| secretARN | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains the key-value pairs required to connect to your Gmail. The secret must contain a JSON structure with the following keys: {
"adminAccountEmailId": "${adminAccountEmailId}",
"clientEmailId": "${clientEmailId}",
"privateKey": "${privateKey}"
} |
| version | The version of the template that's currently supported. |
# How Amazon Q Business connector crawls Gmail ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an Gmail data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your Gmail instance. ACL crawling behavior differs between the two Gmail connector versions.
**Note**
**ACL behavior by connector version:**
**Latest connector:** ACL and identity crawling is automatically enabled and cannot be disabled. Only applies to email messages and draft emails - attachments are not supported.
**Legacy connector:** ACL and identity crawling can be manually configured during setup. Applies to both messages and attachments when attachment crawling is enabled.
The legacy Gmail connector for Amazon Q Business crawls 2 primary content types: messages (email along with metadata such as subject, from, or to) and attachments. Each email message (in sent and inbox) and its respective attachments is considered as a separate document with distinct document IDs. Currently, the connector cannot associate an attachment with its parent message, even though attachments inherit permissions from parent messages.
**Note**
**Latest connector limitations:** The latest Gmail connector does not support attachment crawling. The latest Gmail connector does not support attachment crawling. If your organization requires attachment indexing, use the legacy connector instead.
**Permission Inheritance**: ACLs for messages are set based on user email addresses. **Legacy connector only:** Attachments automatically inherit permissions from parent email messages when attachment crawling is enabled.
**ACL indexing**: Individual user synchronization is supported based on email addresses, and domain-wide access is supported using service account authentication.
**Change Management**: ACL changes are supported in both Full Crawl and Incremental or Change Log modes.
**Failure handling** The connector implements a fail-close approach for API failures, with rate limiting handled through queue-based wait time with exponential backoff. When permissions issues occur, documents are skipped from ingestion rather than being made publicly accessible.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
**Note**
**ACL behavior by connector version:**
**New connector:** ACL and identity crawling is automatically enabled and cannot be disabled. No manual configuration is required.
**Original connector:** ACL and identity crawling can be manually configured during setup.
# Gmail data source connector field mappings
Field mappings
You can improve search results and customize your users' chat experience by mapping document attributes from your Gmail data to fields in your Amazon Q index.
With Amazon Q, you can map two types of attributes to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have an attribute mapping already available, or if you want to map additional document attributes to index fields, you can use custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after you create your application and retriever.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Gmail connector supports the following entities and the associated reserved and custom attributes.
**Topics**
+ [
## Messages
](#gmail-field-mappings-messages)
## Messages
| Gmail field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| internalDate | \$1created\$1at | Default | Date |
| id | gmail\$1message\$1is | Custom | String |
| labelIds | gmail\$1message\$1label\$1ids | Custom | String list |
| historyId | gmail\$1message\$1history\$1id | Custom | String |
| subject | gmail\$1subject | Custom | String |
| from | gmail\$1from | Custom | String |
| to | gmail\$1to | Custom | String list |
| cc | gmail\$1cc | Custom | String list |
| bcc | gmail\$1bcc | Custom | String list |
**Note**
**Original connector only:** Field mappings are only available when using the original Gmail connector. The new connector uses optimized default field mappings that cannot be customized.
# IAM role for Amazon Q Business Gmail connector
IAM role
**Note**
**Applies to both connector versions:** The IAM role requirements are the same for both the new and original Gmail connectors. However, the new connector automatically handles VPC configurations, while the original connector allows manual VPC setup.
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Understand error codes in the Amazon Q Business Gmail connector
Error Codes
The following table provides information about error codes you may see for the Gmail connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| GML-5001 | There was a problem while retrieving directory. | There was a problem while retrieving directory because of incorrect credentials. Provide correct credentials and try again. |
| GML-5002 | There was a problem while retrieving user specific Gmail object. | There was a problem while retrieving user specific Gmail object because of incorrect credentials. Provide correct credentials and try again. |
| GML-5003 | Connection lost - A problem occurred while validating credentials. | Connection was lost due to invalid credentials. Provide correct credentials and try again. |
| GML-5004 | There was a problem while retrieving the user list because the API was not responding. | There was a problem while retrieving the user list because the API was not responding. Try again. |
| GML-5100 | There was a problem while retrieving repository configurations. Repository configurations may be empty or incorrect. | Repository configurations should not be empty or incorrect. Provide valid details for repository configurations. |
| GML-5101 | There was a problem while retrieving message entity from repository configurations. No message entity found in repository configurations. | Message entity should not be empty. Check if message entity is present in repository configurations and provide the same if not present. |
| GML-5102 | There was a problem while retrieving attachment entity from repository configurations. No attachment entity found in repository configurations. | Attachment entity should not be empty. Check if attachment entity is present in repository configurations and provide the same if not present. |
| GML-5103 | There was a problem while retrieving field mappings for message entity from repository configurations. Field mappings may be empty or incorrect. | Field mappings should not be empty or incorrect. Provide proper field mappings for message entity in repository configurations. |
| GML-5104 | There was a problem while retrieving field mappings for attachment entity from repository configurations. Field mappings may be empty or incorrect. | Field mappings should not be empty or incorrect. Provide proper field mappings for message entity in repository configurations. |
| GML-5105 | There was a problem while retrieving field mapping values for message entity. Field mapping values may be empty or incorrect. | Field mappings values should not be empty or incorrect. Provide proper field mapping values for message entity in repository configurations. |
| GML-5106 | There was a problem while retrieving field mapping values for attachment entity. Field mapping values may be empty or incorrect. | Field mappings values should not be empty or incorrect. Provide proper field mapping values for message entity in repository configurations. |
| GML-5107 | There was a problem while parsing before/after date filter value. Before/After date format may be incorrect. | Provide correct before/after date format. E.g. yyyy-MM-ddTHH:mm:ssZ. |
| GML-5108 | There was a problem while retrieving client email id. Client email id may be empty or incorrect. | The client email id should not be empty or incorrect. Provide correct client email id. |
| GML-5109 | There was a problem while retrieving admin account email id. Admin account email id may be empty or incorrect. | The admin account email id should not be empty or incorrect. Provide correct admin account email id. |
| GML-5110 | There was a problem while retrieving private key. Private key may be empty or incorrect. | The private key should not be empty or incorrect. Provide correct private key. |
| GML-5111 | One or more of the provided filter regex are invalid. | Provide correct regex value in filter fields. |
| GML-5200 | There was a problem while retrieving Gmail items. | There was a problem while retrieving Gmail items because user is not provided. Ensure that user is not empty. |
| GML-5201 | There was a problem while retrieving the message body because the API was not responding. | There was a problem while retrieving the message body because the API was not responding. Try again. |
| GML-5202 | There was a problem while retrieving the message subject because the API was not responding. | There was a problem while retrieving the message subject because the API was not responding. Try again. |
| GML-5203 | There was a problem while retrieving the attachment because the API was not responding. | There was a problem while retrieving the attachment because the API was not responding. Try again. |
| GML-5204 | There was a problem while retrieving the message metadata because the API was not responding. | There was a problem while retrieving the message metadata because the API was not responding. Try again. |
| GML-5205 | There was a problem while retrieving the attachment metadata because the API was not responding. | There was a problem while retrieving the attachment metadata because the API was not responding. Try again. |
| GML-5206 | There was a problem while retrieving the message because the API was not responding. | There was a problem while retrieving the message because the API was not responding. Try again. |
| GML-5500 | Connection timed out - API is not responding. The threshold number of API calls has been exceeded. | Timeout exception occurred due to API not responding. The threshold number of API hits has been exceeded. Try again. |
# Connecting Google Calendar to Amazon Q Business (Preview)
Google Calendar (*Preview*)
**Note**
The Google Calendar connector is in preview release and is subject to change.
Google Calendar is an online calendar tool developed by Google. You can connect a Google Calendar instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# Known limitations for the Google Calendar connector (Preview)
](gcal-limitations.md)
+ [
# Google Calendar connector overview (Preview)
](gcal-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Google Calendar (Preview)
](gcal-prereqs.md)
+ [
# Connecting Amazon Q Business to Google Calendar using the console (Preview)
](gcal-console.md)
+ [
# Connecting Amazon Q Business to Google Calendar using APIs
](gcal-api.md)
+ [
# How Amazon Q Business connector crawls Google Calendar ACLs
](gcal-user-management.md)
+ [
# Google Calendar data source connector field mappings
](google-calendar-field-mappings.md)
+ [
# IAM role for Amazon Q Business Google Calendar connector (Preview)
](gcal-iam-role.md)
+ [
# Understand error codes in the Amazon Q Business Google Calendar connector (Preview)
](gcal-error-codes.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Google Calendar connector (Preview)
Known limitations
The connector employs a rolling window approach for indexing data. This rolling window mechanism spans a total of six months, with four months of historical data and two months of future data. As the connector syncs and ingests new data, the oldest data that falls beyond the four-month historical window is automatically purged from the index. Simultaneously, new data for the upcoming two months is added to the index, allowing for future data visibility and analysis.
# Google Calendar connector overview (Preview)
Overview
The following table gives an overview of the Google Calendar connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/gcal-overview.html)
# Prerequisites for connecting Amazon Q Business to Google Calendar (Preview)
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Google Calendar, make sure you have:**
+ Created a Google Cloud Platform admin account and have created a Google Cloud project.
+ Activated the Google Calendar API and Admin SDK API in your admin account.
+ Created a service account and downloaded a JSON private key for your Google Calendar. For information about how to create and access your private key, see [Create a service account key](https://cloud.google.com/iam/docs/keys-create-delete#creating) and [Service account credentials](https://cloud.google.com/iam/docs/service-account-creds#key-types) on the Google Cloud website.
On the Google Cloud website:
+ Copied your admin account email, your service account email, and your private key to use for authentication.
+ Added the following Oauth scopes, using an admin role, for your user and the shared directories you want to index:
+ https://www.googleapis.com/auth/admin.directory.user.readonly
+ https://www.googleapis.com/auth/gmail.readonly
In your AWS account, make sure you have:
+ Created an Amazon Q Business application.
+ Created an Amazon Q Business retriever and added an index.
+ Created an IAM role for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Google Calendar authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Google Calendar authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Google Calendar using the console (Preview)
Using the console
The following procedure outlines how to connect Amazon Q Business to Google Calendar using the AWS Management Console.
**Connecting Amazon Q to Google Calendar**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Google Calendar** data source to your Amazon Q application.
1. Then, on the **Google Calendar** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. In **Authentication**, Choose between Google service account or OAuth 2.0 authentication, based on your use case.
1. AWS Secrets Manager secret – Choose an existing secret or create a Secrets Manager secret to store your Google Calendar authentication credentials. If you choose to create a secret, an **AWS Secrets Manager secret** window opens.
1. If you choose **Existing**, select an existing secret for **Select secret**.
1. If you choose New, enter the following information in the New AWS Secrets Manager secret section:
1. **Secret Name** – A name for your secret.
1. If you chose Google service account, enter the following information:
1. **Client email** – The email ID of the service account.
1. **Admin account email** –The email ID of the admin user (the email used by the Service Account User) in your Google service account configuration.
1. **Private key** – The private key created in your Google service account.
1. Choose **Save and add secret**.
1. If you chose OAuth 2.0 authentication, enter the details of Secret Name, Client ID, Client secret and Refresh token that you created in your service account. Then, choose Save and add secret.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/gcal-connector.html#gcal-iam).
1. In Sync scope, choose from the following options:
+ **All calendars**: Add all the calendars to the index.
+ **Specific calendars only**: Add email addresses associated to only the calendars you want to include in your index.
+ **Exclude specific calendars**: Add email addresses for the calendars you want to exclude from your index.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. For **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Google Calendar using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
**Topics**
+ [
## Google Calendar configuration properties
](#gcal-configuration-keys)
+ [
## Google Calendar JSON schema
](#gcal-json)
+ [
## Google Calendar JSON schema example
](#s3-api-json-example)
## Google Calendar configuration properties
The following table provides information about configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| connectionConfiguration | Configuration information for the data source. | `object` This property has the following sub-property: `repositoryEndpointMetadata`. | Yes |
| repositoryEndpointMetadata | The endpoint information for the data source. This data source doesn't specify an endpoint. You choose your authentication type: serviceAccount and OAuth2. The connection information is included in an AWS Secrets Manager secret that you provide the secretArn. | `object` This property has the following sub-property: `authType`. | Yes |
| authType | Choose between serviceAccount and OAuth2, based on your use case. | `string` | Yes |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties: `file` and `comment`. | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/gcal-api.html) | A list of objects that map the attributes or field names of your Google calendar to Amazon Q index field names. | `object` `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/gcal-api.html) | No |
| `indexFieldName` | The field name of your Google Drive to Amazon Q index field names. | `string` | Yes |
| `indexFieldType` | The field type of your Google Drive to Amazon Q index field names. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your Google Calendar to Amazon Q index field names. | `string` | Yes |
| `dateFieldFormat` | The date format of your Google Calendar to Amazon Q index field names. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| additionalProperties | Additional configuration options for your content in your data source | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/gcal-api.html) | Yes |
| isCrawlAcl | Specify true to crawl access control information by default from documents. Amazon Q Business crawls ACL information to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. | `boolean` | No |
| fieldForUserId | Specify field to use for UserId for ACL crawling. | `string` | No |
| inclusionUsersList exclusionUsersLists | A list of email IDs to exclude specific users from your Google Calendardata source. Users whose email IDs match these will be excluded from the index, while users whose email IDs do not match will be included. If a file matches both an exclusion and an inclusion, the exclusion takes precedence, and the file will not be included in the index. | `array` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/gcal-api.html) | The type of source. We recommend GOOGLECALENDAR as your data source type. | `string` Valid values are GOOGLECALENDAR. | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/gcal-api.html) | true to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to certain documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls ACL information to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. | `boolean` | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/gcal-api.html) | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: Use `FORCED FULL CRAWL` to freshly re-crawl all content and replace existing content each time your data source syncs with your indexUse.Use `FULL CRAWL` to incrementally crawl only new, modified, and deleted content each time your data source syncs with your index | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/gcal-api.html) | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Google Drive. . | `string` The secret must contain a JSON structure with the following keys: If using Google Service Account authentication: `{"clientEmail": "user account email","adminAccountEmail": "service account email","privateKey": "private key"}If using OAuth 2.0 authentication:{"clientID": "OAuth client ID","clientSecret": "client secret","refreshToken": "refresh token"}` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/gcal-api.html) | The version of this template that's currently supported. | `string` | No |
## Google Calendar JSON schema
The following is the Google Calendar JSON schema:
```
{
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"authType": {
"type": "string",
"enum": [
"OAuth2",
"serviceAccount"
]
}
},
"required": [
"authType"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"calendar": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE",
"STRING_LIST",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"event": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE",
"STRING_LIST"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"fieldForUserId": {
"type": "string"
},
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": [
"true",
"false"
]
}
]
},
"inclusionUsersList": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionUsersList": {
"type": "array",
"items": {
"type": "string"
}
},
"enableDeletionProtection": {
"type": "boolean",
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
}
},
"enableIdentityCrawler": {
"type": "boolean"
},
"syncMode": {
"type": "string",
"enum": [
"FULL_CRAWL",
"FORCED_FULL_CRAWL"
]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"type": {
"type": "string",
"pattern": "GOOGLECALENDAR"
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
## Google Calendar JSON schema example
The following is the Google Calendar JSON schema example:
```
{
{
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"authType": "serviceAccount"
}
},
"repositoryConfigurations": {
"calendar": {
"fieldMappings": [
{
"indexFieldName": "_category",
"indexFieldType": "STRING",
"dataSourceFieldName": "category"
},
{
"indexFieldName": "_source_uri",
"indexFieldType": "STRING",
"dataSourceFieldName": "sourceUrl"
}
]
},
"event": {
"fieldMappings": [
{
"indexFieldName": "_category",
"indexFieldType": "STRING",
"dataSourceFieldName": "category"
},
{
"indexFieldName": "gcal_location",
"indexFieldType": "STRING",
"dataSourceFieldName": "location"
},
{
"indexFieldName": "_created_at",
"indexFieldType": "DATE",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'",
"dataSourceFieldName": "created"
},
{
"indexFieldName": "_last_updated_at",
"indexFieldType": "DATE",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'",
"dataSourceFieldName": "updated"
},
{
"indexFieldName": "gcal_event_start_time",
"indexFieldType": "DATE",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'",
"dataSourceFieldName": "eventStartTime"
},
{
"indexFieldName": "gcal_event_end_time",
"indexFieldType": "DATE",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'",
"dataSourceFieldName": "eventEndTime"
},
{
"indexFieldName": "_source_uri",
"indexFieldType": "STRING",
"dataSourceFieldName": "htmlLink"
},
{
"indexFieldName": "gcal_organizer",
"indexFieldType": "STRING",
"dataSourceFieldName": "organizer"
},
{
"indexFieldName": "gcal_attendees",
"indexFieldType": "STRING",
"dataSourceFieldName": "attendees"
},
{
"indexFieldName": "gcal_recurrence",
"indexFieldType": "STRING",
"dataSourceFieldName": "recurrence"
}
]
}
},
"additionalProperties": {
"fieldForUserId": "email",
"isCrawlAcl": true,
"inclusionUsersList": [
"ABC"
],
"exclusionUsersList": [
"TEST"
],
"enableDeletionProtection": true,
"deletionProtectionThreshold": "2"
},
"type": "GOOGLECALENDAR",
"syncMode": "FORCED_FULL_CRAWL",
"enableIdentityCrawler": true,
"secretArn": "arn:aws::secretsmanager:us-west-2:123:secret:AmazonKendra-GoogleCalendar",
"version": "1.0.0"
}
```
# How Amazon Q Business connector crawls Google Calendar ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an Google Calendar data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your Google Calendar instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Google Calendar data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Google Calendar connector supports the following entities and field mappings.
**Topics**
+ [
## Files
](#gcal-field-mappings-files)
## Files
Calendar
| Google Calendar field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| sourceUrl | \$1sourceUrl | Default | String |
Events
| Google Calendar field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| Location | gcal\$1location | Custom | String |
| eventStartTime | gcal\$1event\$1start\$1time | Custom | Date |
| eventEndTime | gcal\$1event\$1end\$1time | Custom | Date |
| category | \$1category | Default | String |
| created | \$1created\$1at | Default | DateString |
| updated | \$1last\$1updated\$1at | Default | Date |
| htmlLink | \$1source\$1url | Default | String |
| attendees | gcal\$1attendees | Custom | String |
| organizer | gcal\$1organizer | Custom | String |
| recurrence | gcal\$1recurrence | Custom | String |
# IAM role for Amazon Q Business Google Calendar connector (Preview)
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Understand error codes in the Amazon Q Business Google Calendar connector (Preview)
Error Codes
The following table provides information about error codes you may see for the Google Calendar connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| GCAL-5001 | Connection lost - A problem occurred while validating credentials | A problem occurred while validating credentials. Provided credentials may be incorrect. |
| GCAL-5002 | There was a problem while retrieving the directory | There was a problem while retrieving the directory due to incorrect credentials. Provide correct credentials and try again. |
| GCAL-5003 | Connection lost - A problem occurred while validating credentials. | Connection was lost due to invalid credentials. Provide correct credentials and try again. |
| GCAL-5004 | There was a problem while retrieving the user list because the API was not responding. | There was a problem while retrieving the user list because the API was not responding. Try again. |
| GCAL-5100 | There was a problem while generating the new access token. | |
| GCAL-5101 | There was a problem while retrieving the private key. | The private key may be empty or incorrect. |
| GCAL-5102 | There was a problem while retrieving the http request initializer. | |
| GCAL-5103 | Auth Type can not be null or empty | Enter a valid value. |
| GCAL-5104 | Invalid value for Auth Type | Enter a valid value. |
| GCAL-5105 | Only String, String List, Date and Long formats are supported for the indexFieldType in all the field mappings. | Please provide the supported format only for the indexFieldType in all the fieldMappings. |
| GCAL-5106 | There was a problem while retrieving client email id. Client email id may be empty or incorrect. | Client email id can not be empty or incorrect. Provide the proper values. |
| GCAL-5107 | Client Email ID length is more than the size limit. | Client Email should be less than 255 characters. |
| GCAL-5108 | There was a problem while retrieving admin account email id. Admin account email id may be empty or incorrect. | The admin account email id should not be empty or incorrect. Provide the correct email id. |
| GCAL-5109 | Admin Account Email ID length is more than the size limit. | Admin Email should be less than 255 characters. |
| GCAL-5110 | There was a problem while retrieving client id. Client id is empty or incorrect | The client id should not be empty or incorrect. Provide the correct email id. |
| GCAL-5111 | There was a problem while retrieving client secret. Client secret is empty or incorrect | Enter a valid value. |
| GCAL-5112 | There was a problem while retrieving refresh token. Refresh token is empty or incorrect | Provide the correct refresh token. |
| GCAL-5113 | The connection configuration in your data source configuration is missing. | Enter valid connection configuration details and try again. |
| GCAL-5114 | The repository endpoint metadata in your data source configuration is missing. | Enter valid repository endpoint metadata details and try again. |
| GCAL-5115 | The repository credentials in your data source configuration is missing. | Enter valid repository credentials details and try again. |
| GCAL-5116 | Invalid client email | Enter valid client email and try again. |
| GCAL-5117 | Invalid admin account email | Enter valid admin account email and try again. |
| GCAL-5118 | There was an error parsing the field value for field %s. | Size has exceeded the maximum allowable limit. The maximum size permitted is 1000. |
| GCAL-5119 | There was an error parsing the field value. The size of the filter pattern exceeded the maximum number of characters allowed. | The maximum size permitted is 1000. |
| GCAL-5400 | The identity crawler connection configuration in your data source configuration is missing. | Enter valid identity crawler connection configuration details and try again. |
| GCAL-5401 | The identity crawler repository endpoint metadata in your data source configuration is missing. | Enter valid identity crawler repository endpoint metadata details and try again. |
| GCAL-5402 | The identity crawler repository credentials in your data source configuration is missing. | Enter valid identity crawler repository credentials details and try again. |
| GCAL-5403 | Auth Type can not be null or empty | Enter a valid value. |
| GCAL-5404 | Invalid value for Auth Type | Enter a valid value. |
| GCAL-5500 | Connection timed out - API is not responding. | The threshold number of API hits has been exceeded. |
# Connecting Google Drive to Amazon Q Business
Google Drive
Google Drive is a cloud-based file storage service. Amazon Q Business can connect to your Google Drive instances. You can connect Google Drive instance to Amazon Q—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
After you integrate Amazon Q with Google Drive, users can ask questions about content stored in their Google Drive. For example, users can inquire about key findings from Google Docs, presentation highlights from Google Slides, or search for specific information across multiple document types. The integration enables users to quickly access and understand information from their Google Drive content, regardless of file location or type, while providing contextual details such as publication dates, modification history, and document ownership—all contributing to more efficient information discovery and better-informed decision making.
**Topics**
+ [
# Connecting Google Drive to Amazon Q Business (New)
](googledrive-v2-connector-primary.md)
+ [
# Connecting Google Drive to Amazon Q Business (Original)
](googledrive-v1-connector-primary1.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Google Drive to Amazon Q Business (New)
Google Drive New
With the new connector, you can build and refresh your index significantly faster than before, control the sync scope using a date filter, and enable your end-users to get insights from link sharing-enabled documents that they have accessed before. The new Google Drive connector also performs targeted identity crawls, eliminating the need to crawl all groups within an enterprise.
# Known limitations for the Amazon Q Business Google Drive connector
Known limitations
The Amazon Q Google Drive connector new has the following known limitations:
+ Comments synchronization is not supported in the new version.
+ VPC connectivity is not supported.
+ Custom field mappings are not supported.
+ File type pattern filtering is not supported (use MIME type filtering instead).
+ Document enrichment is not supported.
# Google Drive connector overview
Overview
The following table gives an overview of the Amazon Q Business Google Drive connector new and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/googledrive-v2-overview-primary.html)
# Prerequisites for connecting Amazon Q Business to Google Drive
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Google Drive, make sure you have:**
+ **Either** been granted access by a super admin role **or** are a user with administrative privileges. You do not need a super admin role for yourself if you have been granted access by a super admin role.
+ Configured Google Drive Service Account connection credentials containing your admin account email, client email (service account email), and private key. See [Google Cloud documentation on creating and deleting service account keys](https://cloud.google.com/iam/docs/keys-create-delete).
+ Created a Google Cloud Service Account (an account with delegated authority to assume a user identity) with **Enable G Suite Domain-wide Delegation** activated for server-to-server authentication, and then generated a JSON private key using the account.
**Note**
The private key should be generated after the creation of the service account.
+ Added Admin SDK API and Google Drive API in your user account.
+ Added (or asked a user with a super admin role to add) the following OAuth scopes to your service account using a super admin role. These API scopes are needed to crawl all documents, and access control (ACL) information for all users in a Google Workspace domain:
+ https://www.googleapis.com/auth/drive.readonly—View and download all your Google Drive files
+ https://www.googleapis.com/auth/drive.metadata.readonly—View metadata for files in your Google Drive
+ https://www.googleapis.com/auth/admin.directory.group.readonly—Scope for only retrieving group, group alias, and member information. This is needed for the Amazon Q Identity Crawler.
+ https://www.googleapis.com/auth/admin.directory.user.readonly—Scope for only retrieving users or user aliases. This is needed for listing users in the Amazon Q Identity Crawler and for setting ACLs.
+ https://www.googleapis.com/auth/cloud-platform—Scope for generating access token for fetching content of large Google Drive files.
+ https://www.googleapis.com/auth/forms.body.readonly—Scope for fetching data from Google Forms.
** To support the Forms API, add the following additional scope:**
+ https://www.googleapis.com/auth/forms.body.readonly
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Google Drive authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Google Drive using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Google Drive new using the AWS Management Console.
**Connecting Amazon Q to Google Drive new**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Google Drive** data source to your Amazon Q application.
1. Then, on the **Google Drive** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Authorization**, configure access control settings: Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting *Enable ACLs* to enable ACLs or *Disable ACLs* to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)for more details.
1. **AWS Secrets Manager secret** – Choose an existing secret or create a secret to store your GoogleDrive authentication credentials. If you choose to create a secret, an AWS Secrets Manager secret window opens.
1. If you choose **Existing**, select an existing secret for **Select secret**.
If you choose **New**, enter the following information in the **New AWS Secrets Manager secret** section:
1. **Secret name** – A name for your secret.
1. Enter the following information:
+ **Secret Name** – A name for your secret.
+ **Admin account email** – The email ID of the admin user (the email used by the Service Account User) in your Google service account configuration.
+ **Client email** – The email ID of the service account.
+ **Private Key** – The private key created in your service account.
Then, choose **Save and add secret**.
1. In **Identity crawler**, configure identity crawling settings:
1. **Identity crawling has been turned on for your connector as the ACLs are enabled** – This notification appears when ACLs are enabled.
1. **Manage identity crawling logs** – When enabled, CloudWatch logs will show identities associated with local groups, as crawled during each sync job. If you disable this option post sync job completion (or partial run), you'll need to manually delete any associated identity crawling logs already generated.
+ **Enable identity crawling logs** – Identities crawled during data source sync will be logged.
+ **Disable identity crawling logs** – Identities crawled during data source sync will not be logged.
1. **IAM role** – Amazon Q Business requires an IAM role to access repository credentials and application content:
1. **Choose an option** – Select an existing IAM role or create a new one.
1. In **Sync scope**, configure which content to sync:
1. **Sync contents** – Choose the following options to select contents to sync. To further limit the contents that you want to sync for specific folders or files use the 'Entity regex patterns':
+ **My Drive** – Selected by default. Use this option if you want the files in all of your users’ My Drives to be included.
+ **Shared with me** – Selected by default. Use this option if you want the files from 'Shared with me' to be included.
+ **Shared Drives** – Selected by default. Use this option if you want to include shared drives. You can use the shared drive filter (see below) to sync files from specific shared drives.
1. For **Maximum file size** – You can specify the file size limit in GB for Amazon Q crawling. Amazon Q crawls only files within the defined size limit. The default file size is 50MB. The maximum file size limit is 10 GB. Files must be larger than 0 MB and no larger than 10 GB. You can go up to 10 GB (10240 MB) if you enable **Video files** in **Multi-media content** configuration, and up to 2 GB (2048 MB) if you enable **Audio files** in **Multi-media content configuration**.
1. In **Additional configuration - *optional***, configure additional filtering options. All content will be indexed by default. However, you can also limit the scope with these additional options:
1. **Date filter** – Add a date range to filter content based on the last modified date:
+ **Start date** – Enter the start date in YYYY/MM/DD format.
+ **End date - *optional*** – Enter the end date in YYYY/MM/DD format.
1. **Shared drives** – Add IDs of shared drives you want to include or exclude in your application:
+ **Include shared drives** – Add shared drive IDs to include.
+ **Exclude shared drives** – Add shared drive IDs to exclude.
1. **Mime types** – Add Mime types to include or exclude in Google Drive account:
+ **Include mime types** – Add MIME types to include (e.g., `application/vnd.google-apps.document` for Google Docs, `application/pdf` for PDF files).
+ **Exclude mime types** – Add MIME types to exclude.
1. **Multi-media content configuration – optional** – To enable content extraction from embedded images and visuals in documents, choose **Visual content in documents**. For more information, see [Extracting semantic meaning from embedded images and visuals](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/extracting-meaning-from-images.html).
To extract audio transcriptions and video content, enable **Audio Files**. To extract video content, enable **Video files**. For more information, see [Extracting semantic meaning from audio and video Content](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/Audio-video-extraction.html).
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# IAM role for Amazon Q Business Google Drive connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:{{secret_id}}"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/{{key_id}}"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
},
{
"Sid": "AllowsAmazonQToCallPrincipalMappingAPIs",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# How Amazon Q Business connector crawls Google Drive ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
The Google Drive connector for Amazon Q Business crawls files with enhanced performance. It supports various file formats, including spreadsheets, presentations, images, audio/video files, and Google Docs™.
**Roles/permissions**: The Google Drive connector translates Google Drive permissions into ACLs that are compatible with Amazon Q Business. There are four primary roles with permissions:
+ Owner - Has full control.
+ Editor - Can modify content, update metadata, and add or remove comments.
+ Commenter - Can view content and add comments.
+ Viewer - Has read-only access.
**Permission Inheritance**: The Google Drive connector is designed to detect and handle hierarchical content organization across My Drive and Shared Drives with improved efficiency. By default, files and subfolders inherit permissions from parent folders. Permissions can be explicitly modified at either the file or folder level to override inherited settings. In this case, the ACLs are a union of the parent ACLs and child ACLs.
**Identity Crawling**: Domain-wide access is supported using service account authentication. Google Drive supports nested groups, meaning that one group can be a member of another. The connector handles complex group structures by flattening group memberships and ensuring that permissions are applied correctly across all levels.
**Change Management**: ACL changes are automatically detected and processed during incremental synchronization.
**Failure handling**: The connector implements a fail-close approach, meaning that if there are permissions-related issues or API failures, a document is skipped from ingestion rather than being made publicly accessible.
# Connecting Amazon Q Business to GoogleDrive using API
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
**Topics**
+ [
## Google Drive configuration properties
](#google-configuration-keys)
+ [
## Google Drive JSON schema
](#googledrive-v2-json)
+ [
## GoogleDrive JSON schema example
](#googledrive-v2-json-example)
+ [
## GoogleDrive minimal configuration example
](#googledrive-v2-json-minimal-example)
## Google Drive configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| type | The connector type. Must be GOOGLEDRIVEV3. | string | Yes |
| connectionConfiguration | Configuration information for the data source connection. | `object` This property has the following sub-properties: `secretArn`, `authType`. | Yes |
| secretArn | The Amazon Resource Name (ARN) of the AWS Secrets Manager secret that contains the Google Drive credentials. | string | Yes |
| authType | The authentication type. The valid value is: SERVICE\$1ACCOUNT. | string | Yes |
| dataEntityConfiguration | Configuration for which Google Drive entities to crawl. | `object` This property has the following sub-properties: `crawlMyDrive`, `crawlSharedWithMe`, `crawlSharedDrives`. | Yes |
| crawlMyDrive | Whether to crawl the user's personal drive. Default is true. | boolean | No |
| crawlSharedWithMe | Whether to crawl files shared with the user. Default is true. | boolean | No |
| crawlSharedDrives | Whether to crawl shared drives. Default is true. | boolean | No |
| accessControlConfiguration | Configuration for access control list (ACL) crawling. | `object` This property has the following sub-property: `crawlAcl`. | Yes |
| crawlAcl | Whether to crawl access control lists for documents. | boolean | No |
| filterConfiguration | Configuration for filtering which content to crawl. | `object` Contains various filtering options including shared drives, MIME types, and date ranges. | No |
| maxFileSizeInMegaBytes | Maximum file size to crawl in megabytes. | string | No |
| exclusionSharedDriveIds | Array of shared drive IDs to exclude from crawling. Maximum 1024 entries. | array | No |
| inclusionSharedDriveIds | Array of shared drive IDs to include in crawling. Maximum 1024 entries. | array | No |
| exclusionMimeTypes | Array of MIME types to exclude from crawling. Maximum 1024 entries. | array | No |
| inclusionMimeTypes | Array of MIME types to include in crawling. Maximum 1024 entries. | array | No |
| modifiedDateBefore | Only crawl files modified before this date. ISO 8601 format (e.g., 2024-12-31T23:59:59Z). | string | No |
| modifiedDateAfter | Only crawl files modified after this date. ISO 8601 format (e.g., 2024-01-01T00:00:00Z). | string | No |
| crawlIdentities | Whether to crawl user and group identities. Not supported in new. | boolean | No |
| deletionProtectionConfiguration | Configuration for deletion protection settings. | `object` This property has the following sub-properties: `enableDeletionProtection`, `deletionProtectionThreshold`. | No |
| enableDeletionProtection | Whether to enable deletion protection. | boolean | No |
| deletionProtectionThreshold | Threshold percentage for deletion protection. | string | No |
| version | Version of the connector configuration. | string | No |
| identityLoggingStatus | Status of identity logging. Valid values are ENABLED and DISABLED. | string | No |
## Google Drive JSON schema
The following is the Google Drive New JSON schema:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["GOOGLEDRIVEV3"]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"authType": {
"type": "string",
"enum": ["SERVICE_ACCOUNT"]
}
},
"required": ["secretArn", "authType"]
},
"dataEntityConfiguration": {
"type": "object",
"properties": {
"crawlMyDrive": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlSharedWithMe": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlSharedDrives": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
}
}
},
"filterConfiguration": {
"type": "object",
"properties": {
"maxFileSizeInMegaBytes": {
"type": "string"
},
"exclusionSharedDriveIds": {
"type": "array",
"maxItems": 1024,
"items": {
"type": "string"
}
},
"inclusionSharedDriveIds": {
"type": "array",
"maxItems": 1024,
"items": {
"type": "string"
}
},
"exclusionMimeTypes": {
"type": "array",
"maxItems": 1024,
"items": {
"type": "string"
}
},
"inclusionMimeTypes": {
"type": "array",
"maxItems": 1024,
"items": {
"type": "string"
}
},
"modifiedDateBefore": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 date-time format (e.g., 2024-12-31T23:59:59Z)"
},
"modifiedDateAfter": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 date-time format (e.g., 2024-01-01T00:00:00Z)"
}
}
},
"accessControlConfiguration": {
"type": "object",
"properties": {
"crawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
}
}
},
"crawlIdentities": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"deletionProtectionConfiguration": {
"type": "object",
"properties": {
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"deletionProtectionThreshold": {
"type": "string"
}
}
},
"version": {
"type": "string"
},
"identityLoggingStatus": {
"type": "string",
"enum": ["ENABLED", "DISABLED"]
}
},
"required": ["type", "connectionConfiguration", "dataEntityConfiguration", "accessControlConfiguration"]
}
```
## GoogleDrive JSON schema example
The following is the GoogleDrive New JSON schema example:
```
{
"type": "GOOGLEDRIVEV3",
"connectionConfiguration": {
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-google-drive-secret",
"authType": "SERVICE_ACCOUNT"
},
"dataEntityConfiguration": {
"crawlMyDrive": true,
"crawlSharedWithMe": true,
"crawlSharedDrives": true
},
"filterConfiguration": {
"maxFileSizeInMegaBytes": "50",
"exclusionSharedDriveIds": ["SharedDrive1"],
"inclusionSharedDriveIds": ["SharedDrive2"],
"exclusionMimeTypes": ["application/vnd.google-apps.folder"],
"inclusionMimeTypes": ["application/pdf", "application/vnd.google-apps.document"],
"modifiedDateBefore": "2024-12-31T23:59:59Z",
"modifiedDateAfter": "2024-01-01T00:00:00Z"
},
"accessControlConfiguration": {
"crawlAcl": true
},
"crawlIdentities": true,
"deletionProtectionConfiguration": {
"enableDeletionProtection": false,
"deletionProtectionThreshold": "10"
},
"version": "3.0.0",
"identityLoggingStatus": "DISABLED"
}
```
## GoogleDrive minimal configuration example
The following is the minimum required configuration for GoogleDrive New:
```
{
"type": "GOOGLEDRIVEV3",
"connectionConfiguration": {
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-google-drive-secret",
"authType": "SERVICE_ACCOUNT"
},
"dataEntityConfiguration": {
"crawlMyDrive": true,
"crawlSharedWithMe": false,
"crawlSharedDrives": false
},
"accessControlConfiguration": {
"crawlAcl": false
}
}
```
# Connecting Amazon Q Business to Google Drive using AWS CloudFormation
Using the CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
**Topics**
+ [
## Google Drive New CloudFormation template
](#googledrive-v2-cfn-template)
## Google Drive New CloudFormation template
The following is the Google Drive New CloudFormation template. Copy and save this template to a file on your local drive.
For more information about CloudFormation templates, see [Working with CloudFormation templates](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html) in the *CloudFormation User Guide*.
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "Template to connect Google Drive New to Amazon Q Business",
"Parameters": {
"ApplicationId": {
"Type": "String",
"Description": "Amazon Q Business Application ID"
},
"IndexId": {
"Type": "String",
"Description": "Amazon Q Business Index ID"
},
"DataSourceName": {
"Type": "String",
"Description": "Name for the Google Drive data source"
},
"RoleArn": {
"Type": "String",
"Description": "IAM Role ARN for the data source"
},
"SecretArn": {
"Type": "String",
"Description": "AWS Secrets Manager ARN containing Google Drive credentials"
}
},
"Resources": {
"GoogleDriveV3DataSource": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": {"Ref": "ApplicationId"},
"IndexId": {"Ref": "IndexId"},
"DisplayName": {"Ref": "DataSourceName"},
"RoleArn": {"Ref": "RoleArn"},
"Configuration": {
"type": "GOOGLEDRIVEV3",
"connectionConfiguration": {
"secretArn": {"Ref": "SecretArn"},
"authType": "SERVICE_ACCOUNT"
},
"dataEntityConfiguration": {
"crawlMyDrive": true,
"crawlSharedWithMe": true,
"crawlSharedDrives": false
},
"accessControlConfiguration": {
"crawlAcl": true
},
"filterConfiguration": {
"maxFileSizeInMegaBytes": "50"
},
"crawlIdentities": false,
"deletionProtectionConfiguration": {
"enableDeletionProtection": true,
"deletionProtectionThreshold": "15"
}
}
}
}
}
}
```
# Connecting Google Drive to Amazon Q Business (Original)
Google Drive (Original)
**Note**
This documentation covers the original version of the Google Drive connector. For new implementations, we recommend using the New Google Drive connector which offers significantly improved performance. The original connector remains available for customers requiring specific features not yet supported in new.
## Known limitations for the Amazon Q Business Google Drive connector
Known limitations
The Amazon Q Google Drive connector has the following known limitations:
+ To make a document available to multiple users in Amazon Q Business, you need to explicitly add each user by their email address. Only documents with specific ACLs, including folder-level ACLs, will be available to your users for query responses within Amazon Q. The **Anyone with the link** feature is not supported.
+ Custom field mapping is not available for Google Drive connector as the Google Drive UI does not support creating custom fields.
+ Google Drive API does not support retrieving comments from a permanently deleted file. Comments are retrievable, however, for trashed files. When a file is trashed, the Amazon Q connector will delete comments from the Amazon Q index.
+ Google Drive API does not return comments present in a .docx file.
# Google Drive connector overview
Overview
The following table gives an overview of the Amazon Q Business Google Drive connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/googledrive-v1-overview-primary.html)
# Prerequisites for connecting Amazon Q Business to Google Drive
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Google Drive, make sure you have:**
+ **Either** been granted access by a super admin role **or** are a user with administrative privileges. You do not need a super admin role for yourself if you have been granted access by a super admin role.
+ Configured Google Drive Service Account connection credentials containing your admin account email, client email (service account email), and private key. See [Google Cloud documentation on creating and deleting service account keys](https://cloud.google.com/iam/docs/keys-create-delete).
+ Created a Google Cloud Service Account (an account with delegated authority to assume a user identity) with **Enable G Suite Domain-wide Delegation** activated for server-to-server authentication, and then generated a JSON private key using the account.
**Note**
The private key should be generated after the creation of the service account.
+ Added Admin SDK API and Google Drive API in your user account.
+ **Optional:** Configured Google Drive OAuth 2.0 connection credentials containing client ID, client secret, and refresh token as connection credentials for a specific user. You need this to crawl individual account data. See [Google documentation on using OAuth 2.0 to access APIs](https://developers.google.com/identity/protocols/oauth2).
+ Added (or asked a user with a super admin role to add) the following OAuth scopes to your service account using a super admin role. These API scopes are needed to crawl all documents, and access control (ACL) information for all users in a Google Workspace domain:
+ https://www.googleapis.com/auth/drive.readonly—View and download all your Google Drive files
+ https://www.googleapis.com/auth/drive.metadata.readonly—View metadata for files in your Google Drive
+ https://www.googleapis.com/auth/admin.directory.group.readonly—Scope for only retrieving group, group alias, and member information. This is needed for the Amazon Q Identity Crawler.
+ https://www.googleapis.com/auth/admin.directory.user.readonly—Scope for only retrieving users or user aliases. This is needed for listing users in the Amazon Q Identity Crawler and for setting ACLs.
+ https://www.googleapis.com/auth/cloud-platform—Scope for generating access token for fetching content of large Google Drive files.
+ https://www.googleapis.com/auth/forms.body.readonly—Scope for fetching data from Google Forms.
** To support the Forms API, add the following additional scope:**
+ https://www.googleapis.com/auth/forms.body.readonly
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Google Drive authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Google Drive using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Google Drive using the AWS Management Console.
**Connecting Amazon Q to Google Drive**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Google Drive** data source to your Amazon Q application.
1. Then, on the **Google Drive** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. For **Authentication** – Choose between **Google service account** and **OAuth 2.0 authentication**, based on your use case.
1. **AWS Secrets Manager secret** – Choose an existing secret or create a Secrets Manager secret to store your GoogleDrive authentication credentials. If you choose to create a secret, an AWS Secrets Manager secret window opens.
1. If you choose **Existing**, select an existing secret for **Select secret**.
If you choose **New**, enter the following information in the **New AWS Secrets Manager secret** section:
1. **Secret name** – A name for your secret.
1. If you chose **Google service account**, enter the following information:
+ **Secret Name** – A name for your secret.
+ **Admin account email** – The email ID of the admin user (the email used by the Service Account User) in your Google service account configuration.
+ **Client email** – The email ID of the service account.
+ **Private Key** – The private key created in your service account.
Then, choose **Save and add secret**.
1. If you chose **OAuth 2.0 authentication**, enter the details of **Secret Name**, **Client ID**, **Client secret** and **Refresh token** that you created in your service account. Then, choose **Save and add secret**.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/google-connector.html#google-iam).
1. In **Sync scope**, for **Sync contents** – Choose from the following options to select content to index:
**Note**
To further limit content to index, use **Entity regex patterns** in the **Additional configuration** section.
+ **My Drive & Shared with me** – **My Drive** contains a user's personal folders and documents. **Shared with me** contains all the folders and documents that have been shared with the user. Select this option to index both.
+ **Shared drives** – **Shared drives** are folders used to store, access, and share files with a team. Select this option to index these.
+ **Comments** – Select this option to index file comments.
**Note**
If you add an inclusion pattern to include certain folder paths or files, you don't need to specify an exclude pattern to include the same folder paths or files.
1. For **Maximum file size** – You can specify the file size limit in GB for Amazon Q crawling. Amazon Q crawls only files within the defined size limit. The default file size is 50MB. The maximum file size limit is 10 GB. Files must be larger than 0 MB and no larger than 10 GB. You can go up to 10 GB (10240 MB) if you enable **Video files** in **Multi-media content** configuration, and up to 2 GB (2048 MB) if you enable **Audio files** in **Multi-media content configuration**.
1. In **Additional configuration - optional**, enter the following optional information:
1. **User email** – Add the user email IDs whose drive files you want to include or exclude.
1. **Shared drives** – The folders and files shared with a team. Add the shared drives that you want to include or exclude.
1. **Mime types** – Add the MIME (Multipurpose Internet Mail Extensions) types that you want to include or exclude from your data sync.
1. **Entity patterns** – Add regular expression patterns to include or exclude certain folders, files, and file types from **My drive**, **Shared with me**, and **Shared drives**. You can add up to 100 patterns.
You can configure the Include/Exclude Regex patterns for File name, File type and File path.
+ **File name** - The name of the file to include/exclude. For example, to index a file with name ’Team roaster.txt’, provide Team roaster.
+ **File type** - The type of the file to include/exclude. For example, .pdf .txt .docx
+ **File path** - The path of the file to include/exclude. For example, to index files only inside the folder ‘Products list’ of a drive, provide /Products list.
1. **Multi-media content configuration – optional** – To enable content extraction from embedded images and visuals in documents, choose **Visual content in documents**. For more information, see [Extracting semantic meaning from embedded images and visuals](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/extracting-meaning-from-images.html).
To extract audio transcriptions and video content, enable **Audio Files**. To extract video content, enable **Video files**. For more information, see [Extracting semantic meaning from audio and video Content](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/Audio-video-extraction.html).
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
**Note**
Documents shared to a specific company domain or with a permission set to **General access: Anyone with the link** must be accessed by at least one user before the documents become visible to users in search.
# IAM role for Amazon Q Business Google Drive connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Understand error codes in the Amazon Q Business Google Drive connector
Error Codes
The following table provides information about error codes you may see for the Google Drive connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| GDL-5101 | The authentication credentials in your data source configuration are invalid. | Verify your Google service account credentials or OAuth 2.0 tokens and try again. |
| GDL-5102 | The authentication type in your data source configuration is missing or invalid. | Enter valid authentication type (Google Service Account or OAuth 2.0) and try again. |
| GDL-5103 | Access denied to Google Drive API. | Ensure your service account has proper domain-wide delegation and API access enabled. |
| GDL-5104 | Rate limit exceeded for Google Drive API. | Wait and retry. Consider reducing sync frequency if the issue persists. |
| GDL-5105 | Invalid folder or file ID specified in filters. | Verify the folder or file IDs in your inclusion/exclusion filters are correct. |
# How Amazon Q Business connector crawls Google Drive ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
The Google Drive connector for Amazon Q Business crawls 2 primary content types: files and comments. It supports various file formats, including spreadsheets, presentations, images, audio/video files, and Google Docs™. Users can configure the connector to include or exclude comments.
**Roles/permissions**: The Google Drive connector translates Google Drive permissions into ACLs that are compatible with Amazon Q Business. There are four primary roles with permissions:
+ Owner - Has full control.
+ Editor - Can modify content, update metadata, and add or remove comments.
+ Commenter - Can view content and add comments.
+ Viewer - Has read-only access.
**Permission Inheritance**: The Google Drive connector is designed to detect and handle hierarchical content organization across My Drive and Shared Drives. By default, files and subfolders inherit permissions from parent folders. Comments inherit their permissions from the corresponding file. Permissions can be explicitly modified at either the file or folder level to override inherited settings. In this case, the ACLs are a union of the parent ACLs and child ACLs.
**Identity Crawling**: Individual user synchronization is supported using email addresses, and domain-wide access is supported using service account authentication. Google Drive supports nested groups, meaning that one group can be a member of another. The connector handles complex group structures by flattening group memberships and ensuring that permissions are applied correctly across all levels.
**Change Management**: ACL changes are supported in both Full Crawl and Incremental/Change Log modes
**Failure handling**: The connector implements a fail-close approach, meaning that if there are permissions-related issues or API failures, a document is skipped from ingestion rather than being made publicly accessible.
**Note**
The Google **Anyone with the link** feature is not supported by Amazon Q Business. To make a document available, you need to explicitly add users by their email address. Only documents with specific ACLs will be available to your users for query responses within Amazon Q.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Google Drive data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
The Amazon Q Google Drive connector supports the following entities and the associated reserved and custom attributes.
## Files
| Google Drive field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| authors | \$1authors | Default | String list |
| mimeType | gd\$1file\$1mime\$1type | Custom | String |
| size | gd\$1size | Custom | Long (numeric) |
| webViewLink | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| modifiedAt | \$1last\$1updated\$1at | Default | Date |
## Comments
| Google Drive field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| authors | \$1authors | Default | String list |
| commentType | gd\$1type | Custom | String |
| createdAt | \$1created\$1at | Default | Date |
| modifiedAt | \$1last\$1updated\$1at | Default | Date |
# Connecting Amazon Q Business to GoogleDrive using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
**Topics**
+ [
## Google Drive configuration properties
](#google-configuration-keys)
+ [
## Google Drive JSON schema
](#googledrive-json)
+ [
## GoogleDrive JSON schema example
](#s3-api-json-example)
## Google Drive configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| connectionConfiguration | Configuration information for the data source. | `object` This property has the following sub-property: `repositoryEndpointMetadata`. | Yes |
| repositoryEndpointMetadata | The endpoint information for the data source. This data source doesn't specify an endpoint. You choose your authentication type: serviceAccount and OAuth2. The connection information is included in an AWS Secrets Manager secret that you provide the secretArn. | `object` This property has the following sub-property: `authType`. | Yes |
| authType | Choose between serviceAccount and OAuth2, based on your use case. | `string` | Yes |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties: `file` and `comment`. | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/googledrive-api.html) | A list of objects that map the attributes or field names of your Google Drive to Amazon Q index field names. | `object` `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/googledrive-api.html) | No |
| `indexFieldName` | The field name of your Google Drive to Amazon Q index field names. | `string` | Yes |
| `indexFieldType` | The field type of your Google Drive to Amazon Q index field names. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your Google Drive to Amazon Q index field names. | `string` | Yes |
| `dateFieldFormat` | The date format of your Google Drive to Amazon Q index field names. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| additionalProperties | Additional configuration options for your content in your data source | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/googledrive-api.html) | Yes |
| isCrawlAcl | Specify true to crawl access control information by default from documents. Amazon Q Business crawls ACL information to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. | `boolean` | No |
| fieldForUserId | Specify field to use for UserId for ACL crawling. | `string` | No |
| maxFileSizeInMegaBytes | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50 MB. The maximum file size should be greater than 0MB and less than or equal to 50 MB. You can use up to 10 GB (10240 MB) if you set videoExtractionStatus to ENABLED in mediaExtractionConfiguration.videoExtractionConfiguration when using CreateDatasource or UpdateDatasource API. Otherwise, you can use up to 2 GB (2048 MB) if you set audioExtractionStatus to ENABLED in mediaExtractionConfiguration.audioExtractionConfiguration when using the CreateDatasource or UpdateDatasource API. | `string` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/googledrive-api.html) | true to index comments in your Google Drive data source. | `boolean` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/googledrive-api.html) | true to index MyDrive and Shared With Me Drives in your Google Drive data source. | `boolean` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/googledrive-api.html) | true to index Shared Drives in your Google Drive data source. | `boolean` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/googledrive-api.html) | A list of regular expression patterns to exclude specific files in your Google Drive data source. Files that match the patterns are excluded from the index. Files that don't match the patterns are included in the index. If a file matches both an exclusion and inclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. | `array` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/googledrive-api.html) | A list of regular expression patterns to include specific files in your Google Drive data source. Files that match the patterns are included in the index. Files that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. | `array` | No |
| type | The type of data source. We recommend GOOOGLEDRIVEV2 as your data source type. | `string` Valid values are `GOOOGLEDRIVEV2` and `GOOGLEDRIVE`. | No |
| enableIdentityCrawler | true to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to certain documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). | `boolean` | Yes |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/googledrive-api.html) | Yes |
| secretARN | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Google Drive. | `string` The secret must contain a JSON structure with the following keys: If using Google Service Account authentication: {
"clientEmail": "user account email",
"adminAccountEmail": "service account email",
"privateKey": "private key"
} If using OAuth 2.0 authentication: {
"clientID": "OAuth client ID",
"clientSecret": "client secret",
"refreshToken": "refresh token"
} | Yes |
| version | The version of this template that's currently supported. | `string` | No |
## Google Drive JSON schema
The following is the Google Drive JSON schema:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["GOOGLEDRIVEV2", "GOOGLEDRIVE"]
},
"syncMode": {
"type": "string",
"enum": ["FORCED_FULL_CRAWL", "FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"authType": {
"type": "string",
"enum": ["serviceAccount", "OAuth2"]
}
},
"required": ["authType"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"file": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "STRING_LIST", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "STRING_LIST"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"maxFileSizeInMegaBytes": {
"type": "string"
},
"isCrawlComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlMyDriveAndSharedWithMe": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlSharedDrives": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"fieldForUserId": {
"type": "string"
},
"excludeUserAccounts": {
"type": "array",
"items": {
"type": "string"
}
},
"excludeSharedDrives": {
"type": "array",
"items": {
"type": "string"
}
},
"excludeMimeTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"includeUserAccounts": {
"type": "array",
"items": {
"type": "string"
}
},
"includeSharedDrives": {
"type": "array",
"items": {
"type": "string"
}
},
"includeMimeTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"includeTargetAudienceGroup": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFilePathFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFilePathFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"type",
"syncMode",
"secretArn",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
## GoogleDrive JSON schema example
The following is the GoogleDrive JSON schema example:
```
{
"type": "GOOGLEDRIVEV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-google-drive-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"authType": "OAuth2"
}
},
"repositoryConfigurations": {
"file": {
"fieldMappings": [
{
"indexFieldName": "file_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"maxFileSizeInMegaBytes": "10240",
"isCrawlComment": "true",
"isCrawlMyDriveAndSharedWithMe": "true",
"isCrawlSharedDrives": "false",
"isCrawlAcl": "true",
"fieldForUserId": "user@example.com",
"excludeUserAccounts": ["user1@example.com", "user2@example.com"],
"excludeSharedDrives": ["SharedDrive1"],
"excludeMimeTypes": ["application/vnd.google-apps.folder"],
"includeUserAccounts": ["user3@example.com"],
"includeSharedDrives": ["SharedDrive2"],
"includeMimeTypes": [
"application/pdf",
"application/vnd.google-apps.document"
],
"includeTargetAudienceGroup": ["group1@example.com"],
"inclusionFileTypePatterns": ["*.pdf"],
"inclusionFileNamePatterns": ["*report*"],
"exclusionFileTypePatterns": ["*.tmp"],
"exclusionFileNamePatterns": ["*draft*"],
"inclusionFilePathFilter": ["documents/"],
"exclusionFilePathFilter": ["drafts/"],
"enableDeletionProtection": "true",
"deletionProtectionThreshold": "15"
}
}
```
# Connecting Amazon Q Business to Google Drive using AWS CloudFormation
Using the CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
**Topics**
+ [
## Google Drive configuration properties
](#google-configuration-keys)
+ [
## Google Drive JSON schema for using the configuration property with AWS CloudFormation
](#google-cfn-json)
+ [
## Google Drive YAML schema for using the configuration property with AWS CloudFormation
](#google-cfn-yaml)
## Google Drive configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| connectionConfiguration | Configuration information for the data source. | `object` This property has the following sub-property: `repositoryEndpointMetadata`. | Yes |
| repositoryEndpointMetadata | The endpoint information for the data source. This data source doesn't specify an endpoint. You choose your authentication type: serviceAccount and OAuth2. The connection information is included in an AWS Secrets Manager secret that you provide the secretArn. | `object` This property has the following sub-property: `authType`. | Yes |
| authType | Choose between serviceAccount and OAuth2, based on your use case. | `string` | Yes |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties: `file` and `comment`. | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/google-cfn.html) | A list of objects that map the attributes or field names of your Google Drive to Amazon Q index field names. | `object` `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/google-cfn.html) | No |
| `indexFieldName` | The field name of your Google Drive to Amazon Q index field names. | `string` | Yes |
| `indexFieldType` | The field type of your Google Drive to Amazon Q index field names. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your Google Drive to Amazon Q index field names. | `string` | Yes |
| `dateFieldFormat` | The date format of your Google Drive to Amazon Q index field names. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| additionalProperties | Additional configuration options for your content in your data source | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/google-cfn.html) | Yes |
| isCrawlAcl | Specify true to crawl access control information by default from documents. Amazon Q Business crawls ACL information to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. | `boolean` | No |
| fieldForUserId | Specify field to use for UserId for ACL crawling. | `string` | No |
| maxFileSizeInMegaBytes | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50 MB. The maximum file size should be greater than 0MB and less than or equal to 50 MB. You can use up to 10 GB (10240 MB) if you set videoExtractionStatus to ENABLED in mediaExtractionConfiguration.videoExtractionConfiguration when using CreateDatasource or UpdateDatasource API. Otherwise, you can use up to 2 GB (2048 MB) if you set audioExtractionStatus to ENABLED in mediaExtractionConfiguration.audioExtractionConfiguration when using the CreateDatasource or UpdateDatasource API. | `string` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/google-cfn.html) | true to index comments in your Google Drive data source. | `boolean` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/google-cfn.html) | true to index MyDrive and Shared With Me Drives in your Google Drive data source. | `boolean` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/google-cfn.html) | true to index Shared Drives in your Google Drive data source. | `boolean` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/google-cfn.html) | A list of regular expression patterns to exclude specific files in your Google Drive data source. Files that match the patterns are excluded from the index. Files that don't match the patterns are included in the index. If a file matches both an exclusion and inclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. | `array` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/google-cfn.html) | A list of regular expression patterns to include specific files in your Google Drive data source. Files that match the patterns are included in the index. Files that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. | `array` | No |
| type | The type of data source. We recommend GOOOGLEDRIVEV2 as your data source type. | `string` Valid values are `GOOOGLEDRIVEV2` and `GOOGLEDRIVE`. | No |
| enableIdentityCrawler | true to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to certain documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). | `boolean` | Yes |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/google-cfn.html) | Yes |
| secretARN | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Google Drive. | `string` The secret must contain a JSON structure with the following keys: If using Google Service Account authentication: {
"clientEmail": "user account email",
"adminAccountEmail": "service account email",
"privateKey": "private key"
} If using OAuth 2.0 authentication: {
"clientID": "OAuth client ID",
"clientSecret": "client secret",
"refreshToken": "refresh token"
} | Yes |
| version | The version of this template that's currently supported. | `string` | No |
## Google Drive JSON schema for using the configuration property with AWS CloudFormation
Google Drive JSON schema
The following is the Google Drive JSON schema and examples for the configuration property for AWS CloudFormation.
**Topics**
+ [
### Google Drive JSON schema for using the configuration property with AWS CloudFormation
](#google-cfn-json-schema)
+ [
### Google Drive JSON schema example for using the configuration property with AWS CloudFormation
](#google-cfn-json-example)
### Google Drive JSON schema for using the configuration property with AWS CloudFormation
Google Drive JSON schema
The following is the Google Drive JSON schema for the configuration property for CloudFormation
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["GOOGLEDRIVEV2", "GOOGLEDRIVE"]
},
"syncMode": {
"type": "string",
"enum": ["FORCED_FULL_CRAWL", "FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"authType": {
"type": "string",
"enum": ["serviceAccount", "OAuth2"]
}
},
"required": ["authType"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"file": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "STRING_LIST", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "STRING_LIST"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"maxFileSizeInMegaBytes": {
"type": "string"
},
"isCrawlComment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlMyDriveAndSharedWithMe": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlSharedDrives": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"fieldForUserId": {
"type": "string"
},
"excludeUserAccounts": {
"type": "array",
"items": {
"type": "string"
}
},
"excludeSharedDrives": {
"type": "array",
"items": {
"type": "string"
}
},
"excludeMimeTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"includeUserAccounts": {
"type": "array",
"items": {
"type": "string"
}
},
"includeSharedDrives": {
"type": "array",
"items": {
"type": "string"
}
},
"includeMimeTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"includeTargetAudienceGroup": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFilePathFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFilePathFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"type",
"syncMode",
"secretArn",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
### Google Drive JSON schema example for using the configuration property with AWS CloudFormation
Google Drive JSON schema example
The following is the Google Drive JSON schema example for the configuration property for CloudFormation
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "CloudFormation GOOGLEDRIVE Data Source Template",
"Resources": {
"DataSourceGoogleDrive": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": "app12345-1234-1234-1234-123456789012",
"IndexId": "indx1234-1234-1234-1234-123456789012",
"DisplayName": "MyGoogleDriveDataSource",
"RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role",
"Configuration": {
"type": "GOOGLEDRIVEV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-google-drive-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"authType": "OAuth2"
}
},
"repositoryConfigurations": {
"file": {
"fieldMappings": [
{
"indexFieldName": "file_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"maxFileSizeInMegaBytes": "50",
"isCrawlComment": "true",
"isCrawlMyDriveAndSharedWithMe": "true",
"isCrawlSharedDrives": "false",
"isCrawlAcl": "true",
"fieldForUserId": "user@example.com",
"excludeUserAccounts": ["user1@example.com", "user2@example.com"],
"excludeSharedDrives": ["SharedDrive1"],
"excludeMimeTypes": ["application/vnd.google-apps.folder"],
"includeUserAccounts": ["user3@example.com"],
"includeSharedDrives": ["SharedDrive2"],
"includeMimeTypes": [
"application/pdf",
"application/vnd.google-apps.document"
],
"includeTargetAudienceGroup": ["group1@example.com"],
"inclusionFileTypePatterns": ["*.pdf"],
"inclusionFileNamePatterns": ["*report*"],
"exclusionFileTypePatterns": ["*.tmp"],
"exclusionFileNamePatterns": ["*draft*"],
"inclusionFilePathFilter": ["documents/"],
"exclusionFilePathFilter": ["drafts/"],
"enableDeletionProtection": "true",
"deletionProtectionThreshold": "15"
}
}
}
}
}
}
```
## Google Drive YAML schema for using the configuration property with AWS CloudFormation
Google Drive YAML schema
The following is the Google Drive YAML schema and examples for the configuration property for AWS CloudFormation:
**Topics**
+ [
### Google Drive YAML schema for using the configuration property with AWS CloudFormation
](#google-cfn-yaml-schema)
+ [
### Google Drive YAML schema example for using the configuration property with AWS CloudFormation
](#google-cfn-yaml-example)
### Google Drive YAML schema for using the configuration property with AWS CloudFormation
Google Drive YAML schema
The following is the Google Drive YAML schema for the configuration property for CloudFormation.
```
type: object
properties:
type:
type: string
enum:
- GOOGLEDRIVEV2
- GOOGLEDRIVE
syncMode:
type: string
enum:
- FORCED_FULL_CRAWL
- FULL_CRAWL
- CHANGE_LOG
secretArn:
type: string
minLength: 20
maxLength: 2048
enableIdentityCrawler:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
connectionConfiguration:
type: object
properties:
repositoryEndpointMetadata:
type: object
properties:
authType:
type: string
enum:
- serviceAccount
- OAuth2
required:
- authType
required:
- repositoryEndpointMetadata
repositoryConfigurations:
type: object
properties:
file:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- STRING_LIST
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
comment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- STRING_LIST
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
additionalProperties:
type: object
properties:
maxFileSizeInMegaBytes:
type: string
isCrawlComment:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
isCrawlMyDriveAndSharedWithMe:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
isCrawlSharedDrives:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
isCrawlAcl:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
fieldForUserId:
type: string
excludeUserAccounts:
type: array
items:
type: string
excludeSharedDrives:
type: array
items:
type: string
excludeMimeTypes:
type: array
items:
type: string
includeUserAccounts:
type: array
items:
type: string
includeSharedDrives:
type: array
items:
type: string
includeMimeTypes:
type: array
items:
type: string
includeTargetAudienceGroup:
type: array
items:
type: string
inclusionFileTypePatterns:
type: array
items:
type: string
inclusionFileNamePatterns:
type: array
items:
type: string
exclusionFileTypePatterns:
type: array
items:
type: string
exclusionFileNamePatterns:
type: array
items:
type: string
inclusionFilePathFilter:
type: array
items:
type: string
exclusionFilePathFilter:
type: array
items:
type: string
enableDeletionProtection:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
default: false
deletionProtectionThreshold:
type: string
default: "15"
version:
type: string
anyOf:
- pattern: 1.0.0
required:
- type
- syncMode
- secretArn
- connectionConfiguration
- repositoryConfigurations
- additionalProperties
```
### Google Drive YAML schema example for using the configuration property with AWS CloudFormation
Google Drive JSON schema example
The following is the Google Drive YAML example for the Configuration property for CloudFormation:
```
AWSTemplateFormatVersion: "2010-09-09"
Description: CloudFormation GOOGLEDRIVE Data Source Template
Resources:
DataSourceGoogleDrive:
Type: AWS::QBusiness::DataSource
Properties:
ApplicationId: app12345-1234-1234-1234-123456789012
IndexId: indx1234-1234-1234-1234-123456789012
DisplayName: MyGoogleDriveDataSource
RoleArn: arn:aws:iam::123456789012:role/qbusiness-data-source-role
Configuration:
type: GOOGLEDRIVEV2
syncMode: FULL_CRAWL
secretArn: arn:aws:secretsmanager:us-west-2:123456789012:secret:my-google-drive-secret
enableIdentityCrawler: "true"
connectionConfiguration:
repositoryEndpointMetadata:
authType: OAuth2
repositoryConfigurations:
file:
fieldMappings:
- indexFieldName: file_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
comment:
fieldMappings:
- indexFieldName: comment_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
additionalProperties:
maxFileSizeInMegaBytes: "50"
isCrawlComment: "true"
isCrawlMyDriveAndSharedWithMe: "true"
isCrawlSharedDrives: "false"
isCrawlAcl: "true"
fieldForUserId: user@example.com
excludeUserAccounts:
- user1@example.com
- user2@example.com
excludeSharedDrives:
- SharedDrive1
excludeMimeTypes:
- application/vnd.google-apps.folder
includeUserAccounts:
- user3@example.com
includeSharedDrives:
- SharedDrive2
includeMimeTypes:
- application/pdf
- application/vnd.google-apps.document
includeTargetAudienceGroup:
- group1@example.com
inclusionFileTypePatterns:
- "*.pdf"
inclusionFileNamePatterns:
- "*report*"
exclusionFileTypePatterns:
- "*.tmp"
exclusionFileNamePatterns:
- "*draft*"
inclusionFilePathFilter:
- documents/
exclusionFilePathFilter:
- drafts/
enableDeletionProtection: "true"
deletionProtectionThreshold: "15"
```
# Connecting Jira to Amazon Q Business
Jira
Jira is a project management tool for software development, product management, and bug tracking. You can connect your Jira instance to Amazon Q Business—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# Known limitations for the Amazon Q Jira connector
](jira-limitations.md)
+ [
# Jira connector overview
](jira-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Jira
](jira-prereqs.md)
+ [
# Setting up Jira for connecting to Amazon Q Business
](jira-credentials.md)
+ [
# Connecting Amazon Q Business to Jira using the console
](jira-console.md)
+ [
# Connecting Amazon Q Business to Jira using APIs
](jira-api.md)
+ [
# Connecting Amazon Q Business to Jira using AWS CloudFormation
](jira-cfn.md)
+ [
# How Amazon Q Business connector crawls Jira ACLs
](jira-user-management.md)
+ [
# Jira data source connector field mappings
](jira-field-mappings.md)
+ [
# IAM role for Amazon Q Business Jira connector
](jira-iam-role.md)
+ [
# Understand error codes in the Amazon Q Business Jira connector
](jira-error-codes.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Amazon Q Jira connector
Known limitations
The Amazon Q Jira connector has the following known limitations:
+ Deleted Issues in Jira are not available through Jira APIs. The Amazon Q Jira connector won't be able to fetch information about deleted Jira issues during incremental syncs.
+ Private and Empty projects aren't crawled by the Amazon Q Jira connector.
# Jira connector overview
Overview
The following table gives an overview of the Amazon Q Business Jira connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-overview.html)
# Prerequisites for connecting Amazon Q Business to Jira
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Jira, make sure you have:**
+ Created Jira API token authentication credentials that include a Jira ID (email ID with domain) and a Jira credential (Jira API token). See the [Atlassian documentation for information about managing API tokens](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).
+ Noted the Jira account URL from your Jira account settings. For example, *https://company.atlassian.net/*.
+ Noted your Jira project key ID from your Jira project settings if you want to crawl only specific Jira projects.
+ If you want to have Amazon Q automatically rotate your secret, ensure that your IAM role includes the `secretsmanager:PutSecretValue` and `secretsmanager:UpdateSecret` permissions.
If you have company-managed Jira projects, you need to perform the following:
+ **Administer Jira Permissions**: The service account - the user configuring the Amazon Q Business integration - must have **Administer Jira** permissions. These permissions are required to read and interpret the permission schemes of company-managed projects to build appropriate Access Control Lists (ACLs). To assign this permission, go to the Settings icon in Jira, then navigate to **System > Global Permissions**. Add the *Administer Jira* permission to the service account.
+ **Email Visibility Settings**: Jira must provide access to the email address of the users for Amazon Q Business to correctly validate document-level permissions. To enable this, update profile settings by navigating to **Profile Picture → Manage Account > Privacy**, and setting **Email Visibility** to Anyone. This is a requirement due to limitations in Jira's API that impact integrations with external tools such as Amazon Q Business.
+ **User and Project-Level Permissions**: The admin user associated with the integration must have at least **Browse Projects** permission in Jira. This can be granted directly or indirectly through a group, project role, or any other applicable configuration. To verify permissions, navigate to the specific Jira project, go to **Project Settings > Permissions**, and confirm that the admin user **Browse Projects** permission. To validate permissions, use the **Permission Helper**. Enter the user alias and select **Browse Projects** permission to check access.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Jira authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
**Note**
For more information on connecting Jira to Amazon Q Business, see [Improve the productivity of your customer support and project management teams using Amazon Q Business and Atlassian Jira](https://aws.amazon.com/blogs/machine-learning/improve-the-productivity-of-your-customer-support-and-project-management-teams-using-amazon-q-business-and-atlassian-jira/) in the *AWS Machine Learning Blog*.
# Setting up Jira for connecting to Amazon Q Business
Setting up Jira
Before you connect Jira to Amazon Q Business, you need to create and retrieve the Jira credentials you will use to connect Jira to Amazon Q. You will also need to add any permissions needed by Jira to connect to Amazon Q.
The following sections give you an overview of how to configure Jira to connect to Amazon Q using either basic authentication or OAuth 2.0 authentication.
**Topics**
+ [
# Basic authentication
](jira-credentials-basic.md)
+ [
# OAuth 2.0 authentication
](jira-credentials-oauth.md)
+ [
# How Amazon Q works with Jira access and refresh tokens
](jira-credentials-notes.md)
+ [
# Checking Jira connectivity
](jira-connection-check.md)
# Basic authentication
You can connect Amazon Q to Jira using basic authentication credentials. The following procedure gives you an overview of how to configure Jira to connect to Amazon Q using basic authentication.
**Configuring Jira basic authentication for Amazon Q**
1. Log in to your account from [Jira](https://jira.atlassian.com/). Note the username you logged in with. You will need this later to connect to Amazon Q.
1. From your Jira home page, copy the Jira URL from your Jira browser URL. For example: *https://example.atlassian.net*. You will need this later to connect to Amazon Q.
1. Then, go to [Security]( https://id.atlassian.com/manage-profile/security/api-tokens.) page in Jira.
1. From the **API tokens** page, select **Create API token**.
1. In the **Create an API token** dialog box that opens, for **Label**, add a name for your API token. Then, select **Create**.
1. From the **Your new API token** dialog box, copy the API token and save it in a text editor of your choice. You can't retrieve the API token once you close the dialog box.
1. Select **Close**.
You now have the username, Jira URL, and Jira API token you need to connect to Amazon Q with basic authentication.
For more information, see [Manage API tokens for your Atlassian account](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) in Atlassian Support.
# OAuth 2.0 authentication
You can connect Amazon Q to Jira using OAuth 2.0 authentication credentials. The following procedures give you an overview of how to configure Jira to connect to Amazon Q using OAuth 2.0 authentication.
**Topics**
+ [
## Step 1: Retrieving username and Jira URL
](#jira-credentials-url)
+ [
## Step 2: Configuring an OAuth 2.0 app integration
](#jira-credentials-oauth-app)
+ [
## Step 3: Retrieving Jira client ID and client Secret
](#jira-credentials-id-secret)
+ [
## Step 4: Generating a Jira access token
](#jira-credentials-access)
+ [
## Step 5: Generating a Jira refresh token
](#jira-credentials-refresh)
+ [
## Step 6: Generating a new Jira access token using a refresh token
](#jira-credentials-refresh-access)
## Step 1: Retrieving username and Jira URL
To connect Jira to Amazon Q, you need your Jira username and your Jira URL. The following procedure shows you how to retrieve these.
**Retrieving username and Jira URL**
1. Log in to your account from the [Jira](https://jira.atlassian.com/). Note the username you logged in with. You will need this later to connect to Amazon Q.
1. From your Jira home page, note your Jira URL from your Jira browser URL. For example: *https://example.atlassian.net*. You will need this later to both configure your OAuth 2.0 token and connect to Amazon Q.
## Step 2: Configuring an OAuth 2.0 app integration
To connect Jira to Amazon Q using OAuth 2.0 authentication, you need to create a Jira OAuth 2.0 app with the necessary permissions. The following procedure shows you how to create this.
**Configuring an OAuth 2.0 app integration**
1. Log in to your account from the [Atlassian Developer page](https://developer.atlassian.com/).
1. Select the profile icon from the top-right corner. Then, from the dropdown menu that opens, select **Developer Console**.
1. From the **Welcome** page, select **Create** and then select **OAuth 2.0 integration**.
1. On the **Create a new OAuth 2.0 (3LO) integration** page, for **Name**, enter a name for the OAuth 2.0 application you are creating. Then, select the **I agree to be bound by Atlassian's developer terms** checkbox, and select **Create**.
The console will display a summary page outlining the details of the OAuth 2.0 app created.
1. From the left navigation menu, choose **Authorization**.
1. From the **Authorization** page, choose **Add** to add **OAuth 2.0 (3LO)** to your app.
1. On the **OAuth 2.0 authorization code grants (3LO) for apps**, enter the Jira URL you copied as the **Callback URL** and then choose **Save changes**.
1. From the **Authorization URL generator** section that appears, choose **Add APIs** to add APIs to your app. This will redirect you to the **Permissions** page.
1. On the **Permissions** page, for **Scopes**, navigate to **User Identity API**. Select **Add**, and then select **Configure**.
1. On the **User Identity API** page, choose **Edit Scopes**, and the add the following `read` scopes:
+ **`read:me`** – View active user profile
+ **`read:account`** – View user profiles
Then, select **Save**.
1. Return to the **Permissions** page. From **Scopes**, navigate to **Jira API**. Select **Add**, and then select **Configure**.
1. On the **Jira API** page, you need to add scopes from both the Classic scopes and Granular scopes sections.
Choose **Edit Scopes**, and add the following scopes:
**In the Classic scopes section, add:**
+ **`read:jira-user`** – View active user profiles
+ **`read:jira-work`** – View Jira issue data
+ **`manage:jira-configuration`** – Manage Jira global settings
**In the Granular scopes section, add:**
+ **`read:application-role:jira`** – View application roles
Select **Save**.
For more information, see [Implementing OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/oauth/getting-started/implementing-oauth-3lo/) and [Determining the scopes required for an operation](https://developer.atlassian.com/cloud/oauth/getting-started/determining-scopes/) in Atlassian Developer.
## Step 3: Retrieving Jira client ID and client Secret
To connect Jira to Amazon Q using OAuth 2.0 authentication, you need to provide a Jira client ID and client secret. The following procedure shows you how to retrieve these.
**Note**
You must create an OAuth 2.0 app before you can retrieve the client ID and client secret. See [Configuring an OAuth 2.0 app integration](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-credentials.html#jira-credentials-oauth-app) for more details.
**Retrieving Jira client ID and client secret**
+ From the left navigation menu, choose **Settings**. Then, scroll down to **Authentication details** section and copy and save the following in a text editor of your choice:
+ Client ID – You will enter this as **App key** in the Amazon Q console.
+ Client Secret – You will enter this as **App secret** in the Amazon Q console.
You will need these to generate your Jira OAuth 2.0 token and also to connect Amazon Q to Jira.
For more information, see [Implementing OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/oauth/getting-started/implementing-oauth-3lo/) and [Determining the scopes required for an operation](https://developer.atlassian.com/cloud/oauth/getting-started/determining-scopes/) in Atlassian Developer.
## Step 4: Generating a Jira access token
To connect Jira to Amazon Q, you need to generate an access token. The following procedure outlines how to generate an access token in Jira.
**Generating your Jira access token**
1. Log in to your account from the [Atlassian Developer page](https://developer.atlassian.com/).
1. Open the OAuth 2.0 app you want to generate a refresh token for.
1. From the left navigation menu, choose **Authorization** again. Then, for **OAuth 2.0 (3LO)**, choose **Configure**.
1. From the **Authorization** page, from **Authorization URL generator**, from **Granular Jira API authorization URL**, copy the URL and save it in a text editor of your choice.
The URL is of the following format:
```
https://auth.atlassian.com/authorize?
audience=api.atlassian.com
&client_id=YOUR_CLIENT_ID
&scope=REQUESTED_SCOPE%20REQUESTED_SCOPE_TWO
&redirect_uri=https://YOUR_APP_CALLBACK_URL
&state=YOUR_USER_BOUND_VALUE
&response_type=code
&prompt=consent
```
1. In the saved authorization URL, update the `state=${YOUR_USER_BOUND_VALUE}` parameter value to any text of your choice. For example, `state=`*sample\$1text*.
For more information, see [What is the state parameter used for?](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#what-is-the-state-parameter-used-for-) in Atlassian Support.
1. Open a web browser of your choice. Then, paste the authorization URL you copied into the browser URL. On the page that opens up, make sure everything is correct and then select **Accept**.
You will be returned to your Jira home page.
1. Copy the URL of the Jira home page and save it in a text editor of your choice. The URL contains the authorization code for your application. You will need this code to generate your Jira access token. The whole section after `code=` is the authorization code.
1. Navigate to Postman.
If you don't have Postman, you can also choose to use cURL to generate a Jira access token. Use the following cURL command to do so:
```
curl --location 'https://auth.atlassian.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{"grant_type": "authorization_code",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"code": "AUTHORIZATION_CODE",
"redirect_uri": "YOUR_CALLBACK_URL"}'
```
1. On the Postman home page, select `POST` as the method, and then enter the following URL in the **Enter URL or paste text** box: `https://auth.atlassian.com/oauth/token`.
1. Then, select **Body** from the menu, and select **raw** **JSON**.
1. In the text box, enter the following code extract, replacing the fields with your credential values:
```
{"grant_type": "authorization_code",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"code": "YOUR_AUTHORIZATION_CODE",
"redirect_uri": "https://YOUR_APP_CALLBACK_URL"}
```
1. Then, select **Send**. If everything is configured correctly, Postman will return an `access-token`. Copy the access token and save it using a text editor of your choice. You will need it to connect Jira to Amazon Q.
For more information, see [Implementing OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/oauth/getting-started/implementing-oauth-3lo/) in Atlassian Developer.
## Step 5: Generating a Jira refresh token
The access token you use to connect Jira to Amazon Q using OAuth 2.0 authentication expires after 1 hour. When it does, you can either repeat the whole authorization process and generate a new access token. Or, you can choose to generate a refresh token. You can use the refresh token to regenerate a new access token when an existing access token expires.
To do this, you add a `%20offline_access` parameter to the end of the `scope` value in the authorization URL you used to generate your access token. The following procedure shows you how to generate a refresh token.
**Generating an Jira refresh token**
1. Log in to your account from the [Atlassian Developer page](https://developer.atlassian.com/).
1. Open the OAuth 2.0 app you want to generate a refresh token for.
1. From the left navigation menu, choose **Authorization** again. Then, for **OAuth 2.0 (3LO)**, choose **Configure**.
1. From the **Authorization** page, from **Authorization URL generator**, from **Granular Jira API authorization URL**, copy the URL and save it in a text editor of your choice.
1. In the saved authorization URL, update the `state=${YOUR_USER_BOUND_VALUE}` parameter value to any text of your choice. For example, `state=`*sample\$1text*.
For more information, see [What is the state parameter used for?](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#what-is-the-state-parameter-used-for-) in Atlassian Support.
1. Then, add the following text at the end of the `scope` value in your authorization URL: `%20offline_access` and copy it. For example:
```
https://auth.atlassian.com/authorize?
audience=api.atlassian.com
&client_id=YOUR_CLIENT_ID
&scope=REQUESTED_SCOPE%20REQUESTED_SCOPE_TWO%20offline_access
&redirect_uri=https://YOUR_APP_CALLBACK_URL
&state=YOUR_USER_BOUND_VALUE
&response_type=code
&prompt=consent
```
1. Open a web browser of your choice and paste the modified authorization URL you copied into the browser URL. On the page that opens up, make sure everything is correct and then select **Accept**.
You will be returned to the Jira console.
1. Copy the URL of the Jira home page and save it in a text editor of your choice. The URL contains the authorization code for your application. You will need this code to generate your Jira refresh token. The whole section after `code=` is the authorization code.
1. Navigate to Postman.
If you don't have Postman, you can also choose to use cURL to generate a Jira access token. Use the following cURL command to do so:
```
curl --location 'https://auth.atlassian.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{"grant_type": "authorization_code",
"client_id": "YOUR CLIENT ID",
"client_secret": "YOUR CLIENT SECRET",
"code": "AUTHORIZATION CODE",
"redirect_uri": "YOUR CALLBACK URL"}'
```
1. On the Postman home page, select `POST` as the method, and then enter the following URL in the **Enter URL or paste text** box: `https://auth.atlassian.com/oauth/token`.
1. Then, select **Body** from the menu, and select **raw** **JSON**.
1. In the text box, enter the following code extract, replacing the fields with your credential values:
```
{"grant_type": "authorization_code",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"code": "YOUR_AUTHORIZATION_CODE",
"redirect_uri": "https://YOUR_APP_CALLBACK_URL"}
```
1. Then, select **Send**. If everything is configured correctly, Postman will return an `refresh-token`.
Copy the refresh token and save it using a text editor of your choice. You will need it to connect Jira to Amazon Q.
For more information, see [Implementing a Refresh Token Flow](https://developer.atlassian.com/cloud/oauth/getting-started/refresh-tokens/) in Atlassian Developer.
## Step 6: Generating a new Jira access token using a refresh token
You can use the refresh token you generated to create a new access token-refresh token pair when an existing access token expires. The following procedure shows you how to generate a refresh token.
**Generating an Jira access token-refresh token pair**
1. Copy the refresh token you generated following the steps in [Step 5: Generating a Jira refresh token](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-credentials.html#jira-credentials-refresh).
1. Navigate to Postman.
If you don't have Postman, you can also choose to use cURL to generate a new Jira access token. Use the following cURL command to do so:
```
curl --location 'https://auth.atlassian.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{"grant_type": "refresh_token",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"refresh_token": "YOUR_REFRESH_TOKEN"}'
```
1. On the Postman home page, select `POST` as the method, and then enter the following URL in the **Enter URL or paste text** box: `https://auth.atlassian.com/oauth/token`.
1. Then, select **Body** from the menu, and select **raw** **JSON**.
1. In the text box, enter the following code extract, replacing the fields with your credential values:
```
{"grant_type": "refresh_token",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"refresh_token": "YOUR REFRESH TOKEN"}
```
1. Then, select **Send**. If everything is configured correctly, Postman will return a new access token-refresh token pair in the following format:
```
{
"access_token": "string,
"expires_in": "expiry time of access_token in second",
"scope": "string",
"refresh_token": "string"
}
```
For more information, see [Implementing a Refresh Token Flow](https://developer.atlassian.com/cloud/oauth/getting-started/refresh-tokens/) and [How do I get a new access token, if my access token expires or is revoked? ](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#how-do-i-get-a-new-access-token--if-my-access-token-expires-or-is-revoked-)in Atlassian Developer.
# How Amazon Q works with Jira access and refresh tokens
The following are important points to note about using Jira access and refresh tokens with Amazon Q:
+ If a Jira access token-refresh token pair you use to connect to Amazon Q are expired or invalid, the Amazon Q sync process fails. If this happens, you need to generate and provide a new pair of tokens.
+ If your access token is valid but you have an invalid refresh token, Amazon Q will sync data until the access token expires (up to 1 hour). After the access token expires, you won't be able to re-generate an access token-refresh token pair using the expired refresh token. When both access token and refresh token expire, the Amazon Q Jira data source connector stops syncing.
+ If an access token expires during the Jira connector sync process, the connector internally regenerates a new pair of tokens using the existing refresh token (if the provided refresh token is valid). After regenerating the new pair of tokens, the old pair is invalidated by Jira and can't be re-used. To sync documents again after the connector auto-regenerates tokens, you must provide a new access token-refresh token pair.
+ If you use OAuth, select **Rotate secret** if you want Amazon Q to rotate the secret automatically so that you don’t have to manually update the secret every time before you sync.
+ As a best practice, use Jira OAuth and the **Rotate secret** feature for the Amazon Q connector.
# Checking Jira connectivity
Before you sync your Jira data source connector after [configuring it](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-console.html), we recommend you check the connection between Amazon Q Business and Jira. The following are the cURL commands you need to check Jira connectivity.
**Topics**
+ [
## Checking basic authentication connectivity
](#jira-connection-check-basic)
## Checking basic authentication connectivity
To check connectivity for a Jira data source connector using basic authentication, use the following cURL command:
```
curl --location 'https://{
"Jira ID": "Jira user name or email host URL",
"Password/Token": "Jira API token"
} | Yes |
| `version` | The version of this template that's currently supported. | `string` | No |
## Jira JSON schema
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
**Topics**
+ [
### Jira configuration properties
](#jira-configuration-keys)
+ [
### Jira JSON schema
](#jira-json)
+ [
### Jira JSON schema example
](#jira-api-json-example)
### Jira configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has the following sub-property: `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-property: `jiraAccountUrl`. | Yes |
| `jiraAccountUrl` | Enter the Jira account URL from your Jira account settings. For example, https://company.atlassian.net/. | `string` | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties: `project`, `attachment`, `comment`, `issue`, `worklog`. | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-api.html) | A list of objects that map the attributes or field names of your Jira pages and assets to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-api.html) | Yes |
| `indexFieldName` | The field name of your Jira project, attachment, comment, issue, or worklog. | `string` | Yes |
| `indexFieldType` | The field type of your Jira project, attachment, comment, issue, or worklog. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your Jira project, attachment, comment, issue, or worklog. | `string` | Yes |
| `dateFieldFormat` | The date format of your Jira project, attachment, comment, issue, or worklog. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-api.html) | Yes |
| `isCrawlAcl` | Specify true to crawl access control information from documents. Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. | `boolean` | No |
| `isRotateSecret` | Specify true if you want to automatically rotate the secret. | `boolean` | No |
| `issuetype` | Customize the issue types to crawl. | `array` The allowed values are `Bug`, `Story`, `Epic`, `Task`. | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-api.html) | Customize the status types, projects, and additional elements to crawl. | `array` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| `fieldForUserId` | Specify field to use for UserId for ACL crawling. | `string` | No |
| `inclusionPatterns` | A list of regular expression patterns to include specific content in your Jira data source. Content that matches the patterns are included in the index. Contents that doesn't match the pattern are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array` | No |
| `exclusionPatterns` | A list of regular expression patterns to exclude specific content in your Jira data source. Content that matches the patterns are excluded from the index. Content that doesn't match the patterns are included in the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array` | No |
| `type` | The type of data source. Specify JIRA as your data source type. | `string` | Yes |
| `enableIdentityCrawler` | Specify true to use the Amazon Q identity crawler to sync identity/principal information on users and groups with access to specific documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). | `boolean` | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-api.html) | Yes |
| `secretArn` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Jira. | `string` The secret must contain a JSON structure with the following keys: {
"Jira ID": "Jira user name or email host URL",
"Password/Token": "Jira API token"
} | Yes |
| `version` | The version of this template that's currently supported. | `string` | No |
### Jira JSON schema
The following is the Jira JSON schema:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"pattern": "JIRA"
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"jiraAccountUrl": {
"type": "string",
"pattern": "https://.*"
}
},
"required": ["jiraAccountUrl"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"issue": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"project": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"worklog": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"issuetype": {
"type": "array",
"items": {
"type": "string",
"enum": ["Bug", "Story", "Epic", "Task"]
}
},
"status": {
"type": "array",
"items": {
"type": "string"
}
},
"project": {
"type": "array",
"items": {
"type": "string"
}
},
"issueSubEntityFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"type",
"syncMode",
"secretArn",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
### Jira JSON schema example
The following is the Jira JSON schema example:
```
{
"type": "JIRA",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-jira-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"jiraAccountUrl": "https://mycompany.atlassian.net"
}
},
"repositoryConfigurations": {
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_body",
"indexFieldType": "STRING",
"dataSourceFieldName": "body",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"issue": {
"fieldMappings": [
{
"indexFieldName": "issue_key",
"indexFieldType": "STRING",
"dataSourceFieldName": "key",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"project": {
"fieldMappings": [
{
"indexFieldName": "project_name",
"indexFieldType": "STRING",
"dataSourceFieldName": "name",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"worklog": {
"fieldMappings": [
{
"indexFieldName": "worklog_time_spent",
"indexFieldType": "STRING",
"dataSourceFieldName": "timeSpent",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"isCrawlAcl": "true",
"maxFileSizeInMegaBytes": "50",
"fieldForUserId": "user_id",
"issuetype": ["Bug", "Story"],
"status": ["Open", "In Progress"],
"project": ["Project1", "Project2"],
"issueSubEntityFilter": ["SubEntity1"],
"inclusionPatterns": ["*"],
"exclusionPatterns": ["*.tmp"],
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
```
# Connecting Amazon Q Business to Jira using AWS CloudFormation
Using CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
**Topics**
+ [
## Jira configuration properties
](#jira-configuration-keys)
+ [
## Jira JSON schema for using the configuration property with AWS CloudFormation
](#jira-cfn-json)
+ [
## Jira YAML schema for using the configuration property with AWS CloudFormation
](#jira-cfn-yaml)
## Jira configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has the following sub-property: `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-property: `jiraAccountUrl`. | Yes |
| `jiraAccountUrl` | Enter the Jira account URL from your Jira account settings. For example, https://company.atlassian.net/. | `string` | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties: `project`, `attachment`, `comment`, `issue`, `worklog`. | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-cfn.html) | A list of objects that map the attributes or field names of your Jira pages and assets to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-cfn.html) | Yes |
| `indexFieldName` | The field name of your Jira project, attachment, comment, issue, or worklog. | `string` | Yes |
| `indexFieldType` | The field type of your Jira project, attachment, comment, issue, or worklog. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your Jira project, attachment, comment, issue, or worklog. | `string` | Yes |
| `dateFieldFormat` | The date format of your Jira project, attachment, comment, issue, or worklog. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-cfn.html) | Yes |
| `isCrawlAcl` | Specify true to crawl access control information from documents. Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. | `boolean` | No |
| `isRotateSecret` | Specify true if you want to automatically rotate the secret. | `boolean` | No |
| `issuetype` | Customize the issue types to crawl. | `array` The allowed values are `Bug`, `Story`, `Epic`, `Task`. | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-cfn.html) | Customize the status types, projects, and additional elements to crawl. | `array` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| `fieldForUserId` | Specify field to use for UserId for ACL crawling. | `string` | No |
| `inclusionPatterns` | A list of regular expression patterns to include specific content in your Jira data source. Content that matches the patterns are included in the index. Contents that doesn't match the pattern are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array` | No |
| `exclusionPatterns` | A list of regular expression patterns to exclude specific content in your Jira data source. Content that matches the patterns are excluded from the index. Content that doesn't match the patterns are included in the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array` | No |
| `type` | The type of data source. Specify JIRA as your data source type. | `string` | Yes |
| `enableIdentityCrawler` | Specify true to use the Amazon Q identity crawler to sync identity/principal information on users and groups with access to specific documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). | `boolean` | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-cfn.html) | Yes |
| `secretArn` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Jira. | `string` The secret must contain a JSON structure with the following keys: {
"Jira ID": "Jira user name or email host URL",
"Password/Token": "Jira API token"
} | Yes |
| `version` | The version of this template that's currently supported. | `string` | No |
## Jira JSON schema for using the configuration property with AWS CloudFormation
Jira JSON schema
The following is the Jira JSON schema and examples for the configuration property for AWS CloudFormation.
**Topics**
+ [
### Jira JSON schema for using the configuration property with AWS CloudFormation
](#jira-cfn-json-schema)
+ [
### Jira JSON schema example for using the configuration property with AWS CloudFormation
](#jira-cfn-json-example)
### Jira JSON schema for using the configuration property with AWS CloudFormation
Jira JSON schema
The following is the Jira JSON schema for the configuration property for CloudFormation
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"pattern": "JIRA"
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"jiraAccountUrl": {
"type": "string",
"pattern": "https://.*"
}
},
"required": ["jiraAccountUrl"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"issue": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"project": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"worklog": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"issuetype": {
"type": "array",
"items": {
"type": "string",
"enum": ["Bug", "Story", "Epic", "Task"]
}
},
"status": {
"type": "array",
"items": {
"type": "string"
}
},
"project": {
"type": "array",
"items": {
"type": "string"
}
},
"issueSubEntityFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"type",
"syncMode",
"secretArn",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
### Jira JSON schema example for using the configuration property with AWS CloudFormation
Jira JSON schema example
The following is the Jira JSON schema example for the configuration property for CloudFormation
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "CloudFormation JIRA Data Source Template",
"Resources": {
"DataSourceJira": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": "app12345-1234-1234-1234-123456789012",
"IndexId": "indx1234-1234-1234-1234-123456789012",
"DisplayName": "MyJiraDataSource",
"RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role",
"Configuration": {
"type": "JIRA",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-jira-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"jiraAccountUrl": "https://mycompany.atlassian.net"
}
},
"repositoryConfigurations": {
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_body",
"indexFieldType": "STRING",
"dataSourceFieldName": "body",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"issue": {
"fieldMappings": [
{
"indexFieldName": "issue_key",
"indexFieldType": "STRING",
"dataSourceFieldName": "key",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"project": {
"fieldMappings": [
{
"indexFieldName": "project_name",
"indexFieldType": "STRING",
"dataSourceFieldName": "name",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"worklog": {
"fieldMappings": [
{
"indexFieldName": "worklog_time_spent",
"indexFieldType": "STRING",
"dataSourceFieldName": "timeSpent",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"isCrawlAcl": "true",
"maxFileSizeInMegaBytes": "50",
"fieldForUserId": "user_id",
"issuetype": ["Bug", "Story"],
"status": ["Open", "In Progress"],
"project": ["Project1", "Project2"],
"issueSubEntityFilter": ["SubEntity1"],
"inclusionPatterns": ["*"],
"exclusionPatterns": ["*.tmp"],
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
}
}
}
}
```
## Jira YAML schema for using the configuration property with AWS CloudFormation
Jira YAML schema
The following is the Jira YAML schema and examples for the configuration property for AWS CloudFormation:
**Topics**
+ [
### Jira YAML schema for using the configuration property with AWS CloudFormation
](#jira-cfn-yaml-schema)
+ [
### Jira YAML schema example for using the configuration property with AWS CloudFormation
](#jira-cfn-yaml-example)
### Jira YAML schema for using the configuration property with AWS CloudFormation
Jira YAML schema
The following is the Jira YAML schema for the configuration property for CloudFormation.
```
type: object
properties:
type:
type: string
pattern: JIRA
syncMode:
type: string
enum:
- FULL_CRAWL
- FORCED_FULL_CRAWL
- CHANGE_LOG
secretArn:
type: string
minLength: 20
maxLength: 2048
enableIdentityCrawler:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
connectionConfiguration:
type: object
properties:
repositoryEndpointMetadata:
type: object
properties:
jiraAccountUrl:
type: string
pattern: https://.*
required:
- jiraAccountUrl
required:
- repositoryEndpointMetadata
repositoryConfigurations:
type: object
properties:
attachment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
comment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
issue:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
project:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
worklog:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
additionalProperties:
type: object
properties:
isCrawlAcl:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
maxFileSizeInMegaBytes:
type: string
fieldForUserId:
type: string
issuetype:
type: array
items:
type: string
enum:
- Bug
- Story
- Epic
- Task
status:
type: array
items:
type: string
project:
type: array
items:
type: string
issueSubEntityFilter:
type: array
items:
type: string
inclusionPatterns:
type: array
items:
type: string
exclusionPatterns:
type: array
items:
type: string
enableDeletionProtection:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
default: false
deletionProtectionThreshold:
type: string
default: "15"
version:
type: string
anyOf:
- pattern: 1.0.0
required:
- type
- syncMode
- secretArn
- enableIdentityCrawler
- connectionConfiguration
- repositoryConfigurations
- additionalProperties
```
### Jira YAML schema example for using the configuration property with AWS CloudFormation
Jira JSON schema example
The following is the Jira YAML example for the Configuration property for CloudFormation:
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "CloudFormation JIRA Data Source Template",
"Resources": {
"DataSourceJira": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": "app12345-1234-1234-1234-123456789012",
"IndexId": "indx1234-1234-1234-1234-123456789012",
"DisplayName": "MyJiraDataSource",
"RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role",
"Configuration": {
"type": "JIRA",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-jira-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"jiraAccountUrl": "https://mycompany.atlassian.net"
}
},
"repositoryConfigurations": {
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_body",
"indexFieldType": "STRING",
"dataSourceFieldName": "body",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"issue": {
"fieldMappings": [
{
"indexFieldName": "issue_key",
"indexFieldType": "STRING",
"dataSourceFieldName": "key",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"project": {
"fieldMappings": [
{
"indexFieldName": "project_name",
"indexFieldType": "STRING",
"dataSourceFieldName": "name",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"worklog": {
"fieldMappings": [
{
"indexFieldName": "worklog_time_spent",
"indexFieldType": "STRING",
"dataSourceFieldName": "timeSpent",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"isCrawlAcl": "true",
"maxFileSizeInMegaBytes": "50",
"fieldForUserId": "user_id",
"issuetype": ["Bug", "Story"],
"status": ["Open", "In Progress"],
"project": ["Project1", "Project2"],
"issueSubEntityFilter": ["SubEntity1"],
"inclusionPatterns": ["*"],
"exclusionPatterns": ["*.tmp"],
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
}
}
}
}
```
# How Amazon Q Business connector crawls Jira ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
Jira organizes work into Projects, which serve as containers for Issues—the core tasks, bugs, or stories that teams track. Each issue belongs to a project and can have Comments, Attachments, and Worklogs to facilitate collaboration, provide context, and track time spent. Projects can be Team-Managed (private, limited, or open) or Company-Managed, offering flexibility in workflows and permissions. When you connect an Jira data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your Jira instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
## Projects
Jira organizes work into Projects, which serve as containers for Issues—the core tasks, bugs, or stories that teams track. Each issue belongs to a project and can have Comments, Attachments, and Worklogs to facilitate collaboration, provide context, and track time spent. Projects can be Team-Managed (private, limited, or open) or Company-Managed, offering flexibility in workflows and permissions. When you connect an Jira data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your Jira instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
## Identity crawling
The Jira connector extracts project-level permissions based on the project key. It identifies direct users and group members, capturing their account IDs and emails. Federated groups, synchronized from external identity providers, appear as local groups in Jira but are managed externally. The connector respects Jira’s permission structure, ensuring that permissions remain intact even when users are removed and later reinstated. Suspended users are included in API responses but marked as inactive, preventing unauthorized access.
**Note**
For all types of projects, you must have at least 'Browse Projects' permissions (direct or indirect), and Email visibility must be set to "Anyone" for AWS to validate permissions correctly. The "Anyone" email visibility setting is required for proper integration with AWS and other third-party tools due to Jira's API limitations.
## Permissions inheritance
Global Permissions determine who can access the Jira instance and perform high-level actions. Project Permissions, governed by permission schemes, define user access within projects, such as viewing, editing, or assigning issues. In Company-Managed projects, permissions flow from the Jira instance down to projects and further to issues, attachments, comments, and worklogs. Issue Security Schemes further restrict access to specific issues within a project. In Team-Managed projects, access is defined by project roles and project visibility settings: **Open** (accessible to all), **Limited** (viewable by all but editable only by members), and **Private** (restricted to project members). While permissions in Company-Managed projects follow a structured hierarchy, Team-Managed projects rely on role-based access. Inheritance applies at the project level, meaning that issues, comments, attachments, and worklogs inherit permissions from their parent project. However, Issue Security Levels can override project permissions by restricting visibility at an issue level.
## ACL mapping
Before enabling ACL-based document access for Jira within Amazon Q Business, it is important to understand how permissions and groups are mapped between Jira and Amazon Q, especially given the structural differences between Team-Managed and Company-Managed projects.
**Team-Managed Projects**: For Team-Managed projects in Jira Software Cloud, ACL mapping is straightforward. The permissions for such projects are configured on the **Project Settings > Access** tab, where you will find a list of users and groups along with their associated project roles. For these projects, a single group is created in Amazon Q Business using the format `projectKey:[ProjectKey]` (for example, `projectKey:TestProject`). This group is attached to all documents under the project, including the project-level document, issues, comments, worklogs, and attachments. All users listed in the **Access** tab will have visibility into all project documents, regardless of their roles.
**Company-Managed Projects**: Company-Managed projects offer more granular access control and therefore require a more complex mapping strategy. To determine document visibility, it is necessary to review two areas within the Jira project:
+ **Project Settings > People**, which lists users and groups along with their project roles. Inclusion in this list does not guarantee document access even for Administrator roles.
+ **Project Settings > Permissions** The **Browse Projects** permission governs who can view the project and its issues. This setting can include a variety of grant types, such as specific groups, project roles, individual users, or dynamic conditions like issue assignees. Ensure users have all necessary permissions listed in [Prerequisites](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/jira-prereqs.html).
Jira also supports issue-level security, which can override the broader **Browse Projects** settings by enforcing granular access rules on a per-issue basis. You need to consider this label during ACL mapping.
Following is an example of how group mappings in Amazon Q Business for Company-Managed projects are established:
+ **Project**: A group named `TestProject` is created, comprising all users who have been granted **Browse Projects** permission, regardless of grant type.
+ **Issue-Level Document**: In the example issue `Test1`, group assignments depend on permissions:
+
+ If a user gains access through project-level permissions, the group `ProjectBasedBrowseKey:Test` is used.
+ If access is granted through dynamic conditions such as the user being the assignee, the group `IssueBasedBrowseKey:Test1` is used.
+ If both types of access mechanisms exist, users may belong to both groups.
+ **Issue with Issue-Level Security Enabled**: Access requires both project/issue-based browse permissions and issue-specific security clearance. The condition becomes: `(ProjectBasedBrowseKey:Test OR IssueBasedBrowseKey:Test1) AND IssueLevelKey:Test1`.
+ **Comments, Attachments, and Worklog**s: These documents inherit the same access control as the associated issue. Therefore, the same issue-level logic applies..
## Change management
Change Log Mode in Amazon Q Business enables incremental updates by capturing modifications made to content in Jira. Instead of re-indexing all documents, it indexes only newly added, updated, or deleted items since the last crawl. Any changes to user or group access permissions are also recorded, ensuring accurate and up-to-date indexing.
## Failure handling
The Jira connector follows a fail-close approach, skipping documents from ingestion in case of API failures or permission-related issues. If a document has no ACLs attached and ACL enforcement is enabled by the admin, it will be ingested and made publicly accessible to configured users.
## More information
For more information about ACLs, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Jira data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Jira connector supports the following entities and the associated reserved and custom attributes.
**Topics**
+ [
## Projects
](#jira-field-mappings-projects)
+ [
## Issues
](#jira-field-mappings-ticket-issues)
+ [
## Comments
](#jira-field-mappings-comments)
+ [
## Attachments
](#jira-field-mappings-attachments)
+ [
## Worklogs
](#jira-field-mappings-worklogs)
## Projects
| Jira field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | j\$1title | Custom | String |
| project\$1key | j\$1project\$1key | Custom | String |
| lead | j\$1lead | Custom | String list |
| url | \$1source\$1uri | Default | String |
## Issues
| Jira field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | j\$1title | Custom | String |
| issue\$1key | j\$1issue\$1key | Custom | String |
| status | j\$1status | Custom | String |
| project\$1name | j\$1project\$1name | Custom | String |
| projectKey | j\$1project\$1key | Custom | String |
| authors | \$1authors | Default | String list |
| assignee | j\$1assignee | Custom | String |
| created\$1at | \$1created\$1at | Default | Date |
| updated\$1at | \$1last\$1updated\$1at | Default | Date |
| url | \$1source\$1uri | Default | String |
| issue\$1type | j\$1issue\$1type | Custom | String |
| priority | j\$1priority | Custom | String |
| resolution | j\$1resolution | Custom | String |
| affects\$1version | j\$1affects\$1version | Custom | String |
| fix\$1version | j\$1fix\$1version | Custom | String |
| labels | j\$1labels | Custom | String |
| environment | j\$1environment | Custom | String |
| reporter | j\$1reporter | Custom | String |
| votes | j\$1votes | Custom | String |
| watchers | j\$1watchers | Custom | String |
| due | j\$1due | Custom | String |
| resolved | j\$1resolved | Custom | String |
## Comments
| Jira field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| authors | \$1authors | Default | String list |
| title | j\$1title | Custom | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| project\$1name | j\$1project\$1name | Custom | String |
| project\$1key | j\$1project\$1key | Custom | String |
| issue\$1key | j\$1issue\$1key | Custom | String |
| url | \$1source\$1uri | Default | String |
## Attachments
| Jira field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | j\$1title | Custom | String |
| authors | \$1authors | Default | String list |
| size | j\$1size | Custom | String |
| createdAt | \$1created\$1at | Default | Date |
| url | \$1source\$1uri | Default | String |
| project\$1name | j\$1project\$1name | Custom | String |
| project\$1key | j\$1project\$1key | Custom | String |
| issue\$1key | j\$1issue\$1key | Custom | String |
## Worklogs
| Jira field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | j\$1title | Custom | String |
| authors | \$1authors | Default | String list |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| url | \$1source\$1uri | Default | String |
| project\$1name | j\$1project\$1name | Custom | String |
| project\$1key | j\$1project\$1key | Custom | String |
| issue\$1key | j\$1issue\$1key | Custom | String |
# IAM role for Amazon Q Business Jira connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Understand error codes in the Amazon Q Business Jira connector
Error Codes
The following table provides information about error codes you may see for the Jira connector and suggested resolutions.
| Error code | Error message |
| --- | --- |
| JIRA-5100 | There was a problem while retrieving access token. Access token should not be null or empty. |
| JIRA-5101 | There was an error parsing the field value. The size has exceeded the maximum allowable limit. |
| JIRA-5102 | Jira inclusion pattern list is too large. |
| JIRA-5103 | Some of the inclusion objects exceed the character limit. |
| JIRA-5104 | Jira exclusion pattern size list is too large. |
| JIRA-5105 | Some of the exclusion objects exceed the character limit. |
| JIRA-5106 | There was a problem while retrieving refresh token. Refresh token should not be null or empty. |
| JIRA-5107 | There was a problem while retrieving Jira Credential. Jira Credential should not be null or empty. |
| JIRA-5108 | There was a problem while retrieving Jira Id. Jira Id should not be null or empty. |
| JIRA-5109 | There was a problem while retrieving Auth Type. Auth Type should not be null or empty. |
| JIRA-5110 | There was a problem while retrieving Jira Account Url. Jira Account Url should not be null or empty. |
| JIRA-5111 | JIRA Issue Sub Entity Filter list size is too large. |
| JIRA-5112 | Some of the Jira Issue Sub Entity Filter objects exceed the character limit. |
| JIRA-5113 | Jira Issue Status Filter list size is too large. |
| JIRA-5114 | Some of the Jira Issue Status Filter objects exceeded the character limit. |
| JIRA-5115 | Jira Issue Type Filter list size is too large. |
| JIRA-5116 | Some of the Jira Issue Type Filter objects exceed the character limit. |
| JIRA-5117 | Jira Project Key Filter list size is too large. |
| JIRA-5118 | Some of the JIRA Project Key Filter objects exceed the character limit. |
| JIRA-5119 | Project specific field mappings are not configured for connector. |
| JIRA-5120 | Issue specific field mappings are not configured for connector. |
| JIRA-5121 | Comment specific field mappings are not configured for connector. |
| JIRA-5122 | Attachment specific field mappings are not configured for connector. |
| JIRA-5123 | Worklog specific field mappings are not configured for connector. |
| JIRA-5124 | There was a problem while retrieving crawl type. Crawl Type should not be null or empty. |
# Connecting Microsoft Exchange to Amazon Q Business
Microsoft Exchange
You can connect your Microsoft Exchange enterprise messaging system to Amazon Q Business to unlock valuable organizational knowledge. This connection allows your users to search emails, calendar events, and shared content directly through the Amazon Q web experience.
You can connect your Microsoft Exchange instance to Amazon Q Business using the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API. This enables faster information discovery and improved decision-making across your organization.
**Topics**
+ [
# Microsoft Exchange connector versions
](exchange-versions.md)
+ [
# Known limitations for the Microsoft Exchange connector
](exchange-limitations.md)
+ [
# Microsoft Exchange connector overview
](exchange-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Microsoft Exchange
](exchange-prereqs.md)
+ [
# Connecting using the Latest Microsoft Exchange Connector (Console)
](exchange-console-new.md)
+ [
# Connecting using the Legacy Microsoft Exchange Connector (Console)
](exchange-console-original.md)
+ [
# Connecting Amazon Q Business to Microsoft Exchange using APIs
](exchange-api.md)
+ [
# Connecting Amazon Q Business to Microsoft Exchange (New connector) using APIs
](exchange-new-api.md)
+ [
# How Amazon Q Business connector crawls Exchange ACLs
](exchange-user-management.md)
+ [
# Microsoft Exchange data source connector field mappings
](exchange-field-mappings.md)
+ [
# IAM role for Microsoft Exchange connector
](exchange-iam-role.md)
+ [
# Understand error codes in the Microsoft Exchange connector
](exchange-error-codes.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Microsoft Exchange connector versions
Connector versions
You can choose between two Microsoft Exchange connector versions:
## Latest Microsoft Exchange connector (Recommended)
Latest connector
**Note**
The latest connector provides improved accuracy. We recommend using the latest connector for new implementations. The legacy connector remains available if you need specific features not yet supported in the latest connector.
The latest Microsoft Exchange connector offers a simplified configuration experience:
+ Enhanced accuracy and performance
+ Simplified filtering with Date Range options only
+ Automatic crawling of ACL and identity information
## Legacy Microsoft Exchange connector
Legacy connector
The legacy Microsoft Exchange connector provides full-featured configuration with advanced options:
+ Complete entity type selection including Calendar, OneNotes, and Contacts
+ Advanced filtering options and regex pattern matching
+ Custom field mappings for metadata extraction
+ Configurable sync modes and VPC settings
+ Domain-based email filtering and inclusion rules
+ Manual ACL and identity crawling configuration
# Known limitations for the Microsoft Exchange connector
Known limitations
**Note**
**Legacy version notice:** We recommend using the latest connector for improved performance and retrieval quality. The following limitations apply only to the legacy connector version.
The original Microsoft Exchange connector has these known limitations:
+ When you enable Access Control Lists (ACLs), the "Sync only new or modified content" option is not available due to Microsoft Exchange API limitations. Use "Full sync" or "New, modified, or deleted content sync" modes instead, or disable ACLs to use this sync mode.
# Microsoft Exchange connector overview
Overview
The following table shows the Amazon Q Business Microsoft Exchange connector features and capabilities.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/exchange-overview.html)
# Prerequisites for connecting Amazon Q Business to Microsoft Exchange
Prerequisites
**In Microsoft Exchange, make sure you have:**
+ Created a Microsoft Exchange account in Office 365.
+ Copied your Microsoft 365 tenant ID. You can find your tenant ID in the **Properties** of your Azure Active Directory Portal or in the Microsoft Entra Admin portal. For more information, see [Find your Microsoft 365 tenant ID](https://learn.microsoft.com/en-us/sharepoint/find-your-office-365-tenant-id) on the Microsoft website.
+ Configured an OAuth 2.0 credential token containing a client ID and client secret.
+ Added the following permissions for the connector application:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/exchange-prereqs.html)
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Microsoft Exchange authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting using the Latest Microsoft Exchange Connector (Console)
Using the latest connector (Console)
The latest Microsoft Exchange connector provides a simplified configuration experience with essential features. The following procedure shows how to connect Amazon Q Business to Microsoft Exchange using the latest connector.
**Connecting Amazon Q to Microsoft Exchange using the latest connector**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Microsoft Exchange (latest)** data source to your Amazon Q application.
1. Then, on the **Microsoft Exchange** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
+ **Tenant ID** – Enter your tenant ID. Your Microsoft tenant ID is a globally unique identifier required to configure each connector instance. You can find your tenant ID in the properties section of your Microsoft account dashboard.
1. For **Authentication**, choose between **New** and **Existing**.
1. If you choose **Existing**, choose an existing secret for **Select secret**.
If you choose **New**, enter the following information in the **New AWS Secrets Manager secret** section:
1. **Secret name** – Enter a name for your secret.
1. For **Client ID** and **Client secret**, enter the authentication credential values that you generated from your Exchange account.
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/exchange-connector.html#exchange-iam).
1. For **Additional configuration – *optional***, configure the following options:
+ **Date Range** – Enter the date range for crawling your email content. The end date is optional.
**Note**
**Simplified configuration:** The latest connector automatically crawls email content only with ACL enabled by default. Entity type selection and attachment filtering are not available to keep configuration simple and reliable.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting using the Legacy Microsoft Exchange Connector (Console)
Using the legacy connector (Console)
The legacy Microsoft Exchange connector provides comprehensive configuration options including entity type selection, field mappings, and VPC settings. The following procedure shows how to connect Amazon Q Business to Microsoft Exchange using the legacy connector.
**Connecting Amazon Q to Microsoft Exchange using the legacy connector**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Microsoft Exchange** data source to your Amazon Q application.
1. Then, on the **Microsoft Exchange** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
+ **Tenant ID** – Enter your tenant ID. Your Microsoft tenant ID is a globally unique identifier required to configure each connector instance. You can find your tenant ID in the properties section of your Microsoft account dashboard.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. **Authentication** – Choose between **New** and **Existing**.
1. If you choose **Existing**, select an existing secret for **Select secret**.
If you choose **New**, enter the following information in the **New AWS Secrets Manager secret** section:
1. **Secret name** – A name for your secret.
1. For **Client ID**, **Client secret** – Enter the authentication credential values that you generated from your Exchange account.
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/exchange-connector.html#exchange-iam).
1. In **Sync scope**, choose from the following options:
+ **UserIDs** – Choose to filter content by specific user email IDs.
+ **User email ID** – Upload a file with user email IDs to filter content. Format email IDs on separate lines in the file.
+ **Include patterns** – Specify patterns to include specific content.
+ **Exclude patterns** – Specify patterns to exclude specific content.
1. For **Maximum file size**, specify the file size limit in MBs that Amazon Q will crawl. Amazon Q crawls only files within the size limit you define. The default file size is 50MB. The maximum file size must be greater than 0MB and less than or equal to 50MB.
1. For **Additional configuration – *optional***, configure the following options:
+ **Entity types** – Choose whether to crawl the following entities: **Calendar**, **OneNotes**, and **Contacts**.
+ **Calendar crawling** – Enter the date range for which the connector will crawl your calendar content.
+ **Include email** – Enter the email from domains, email to domains, and subjects you wish to include or exclude in your application.
+ **Shared folders access** – Enable ACL crawling for shared folders.
+ **Regex for domains** – Add patterns to include and exclude certain email domains from your application.
+ **Regex patterns** – Add regular expression patterns to include or exclude certain files. You can add up to 100 patterns.
1. **Multi-media content configuration – optional** – To enable content extraction from embedded images and visuals in documents, choose **Visual content in documents**.
To extract audio transcriptions and video content, enable processing for the following file types:
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Microsoft Exchange using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
## Microsoft Exchange JSON schema
The following shows the Microsoft Exchange JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"minLength": 36,
"maxLength": 36
}
},
"required": ["tenantId"]
}
}
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"email": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE","LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
},
"calendar": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
},
"contacts": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
},
"notes": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
}
},
"required": ["email"
]
},
"additionalProperties": {
"type": "object",
"properties": {
"inclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionUsersList": {
"type": "array",
"items": {
"type": "string",
"format": "email"
}
},
"exclusionUsersList": {
"type": "array",
"items": {
"type": "string",
"format": "email"
}
},
"s3bucketName": {
"type": "string"
},
"inclusionUsersFileName": {
"type": "string"
},
"exclusionUsersFileName": {
"type": "string"
},
"inclusionDomainUsers": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionDomainUsers": {
"type": "array",
"items": {
"type": "string"
}
},
"crawlCalendar": {
"type": "boolean"
},
"crawlNotes": {
"type": "boolean"
},
"crawlContacts": {
"type": "boolean"
},
"crawlFolderAcl": {
"type": "boolean"
},
"startCalendarDateTime": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
},
{
"type": "string",
"pattern": ""
}
]
},
"endCalendarDateTime": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
},
{
"type": "string",
"pattern": ""
}
]
},
"subject": {
"type": "array",
"items": {
"type": "string"
}
},
"emailFrom": {
"type": "array",
"items": {
"type": "string",
"format": "email"
}
},
"emailTo": {
"type": "array",
"items": {
"type": "string",
"format": "email"
}
},
"maxFileSizeInMegaBytes": {
"type": "string"
}
},
"required": []
},
"syncMode": {
"type": "string",
"enum": [
"FORCED_FULL_CRAWL",
"FULL_CRAWL",
"CHANGE_LOG"
]
},
"type" : {
"type" : "string",
"pattern": "MSEXCHANGE"
},
"secretArn": {
"type": "string"
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint for the data source. |
| repositoryEndpointMetadata | The endpoint information for the data source. |
| tenantId | The Microsoft 365 tenant ID. You can find your tenant ID in the Properties of your Azure Active Directory Portal. |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/exchange-api.html) | A list of objects that map the attributes or field names of your Microsoft Exchange data source. |
| secretARN | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Exchange data source. This includes your client ID and your client secret. |
| additionalProperties | Additional configuration options for content in your data source |
| inclusionPatterns [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/exchange-api.html) | A list of regular expression patterns to include specific files in your Exchange data source. Files that match the patterns are included in the index. Files that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence and the file isn't included in the index. |
| exclusionPatterns[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/exchange-api.html) | A list of regular expression patterns to exclude specific files in your Exchange data source. Files that match the patterns are excluded from the index. Files that don't match the patterns are included in the index. If a file matches both an exclusion and inclusion pattern, the exclusion pattern takes precedence and the file isn't included in the index. |
| startCalendarDateTime | Use to specify the date and time for Calendar content to be crawled by Amazon Q. |
| endCalendarDateTime | Use to specify the date and time for Calendar content to be crawled by Amazon Q. |
| subject | Use to specify email subject lines to be crawled. |
| emailFrom | Use to specify emails to be crawled based on sender. |
| emailTo | Use to specify emails to be crawled based on recipient. |
| maxFileSizeInMegaBytes | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/exchange-api.html) | true to index this content in your Microsoft Exchange data source. Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/exchange-api.html) |
| type | The type of data source. Specify MSEXCHANGE as your data source type. |
| enableIdentityCrawler | true to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). |
| version | The version of this template that's currently supported. |
# Connecting Amazon Q Business to Microsoft Exchange (New connector) using APIs
Using the API (New connector)
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
## Microsoft Exchange new connector JSON schema
The following shows the Microsoft Exchange new connector JSON schema:
```
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["MSEXCHANGEV2"]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"secretArn": {
"type": "string",
"pattern": "^arn:[a-z0-9-\\.]{1,63}:[a-z0-9-\\.]{0,63}:[a-z0-9-\\.]{0,63}:[a-z0-9-\\.]{0,63}:[^/].{0,1023}$"
},
"tenantId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"minLength": 36,
"maxLength": 36
}
},
"required": ["tenantId", "secretArn"]
},
"dataEntityConfiguration": {
"type": "object",
"properties": {
}
},
"filterConfiguration": {
"type": "object",
"properties": {
"startDateFilter": {
"type": "string",
"format": "date-time"
},
"endDateFilter": {
"type": "string",
"format": "date-time"
}
}
},
"deletionProtectionConfiguration": {
"type": "object",
"properties": {
"enableDeletionProtection": {
"type": "boolean"
},
"deletionProtectionThreshold": {
"type": "string",
"pattern": "^(100|[1-9][0-9]?)$"
}
},
"required": ["enableDeletionProtection", "deletionProtectionThreshold"]
}
},
"required": [
"type",
"connectionConfiguration",
"dataEntityConfiguration"
]
}
```
The following table provides information about important JSON keys to configure for the new Microsoft Exchange connector.
| Configuration | Description |
| --- | --- |
| type | The type of data source. Specify MSEXCHANGEV2 for the new Microsoft Exchange connector. |
| connectionConfiguration | Configuration information for connecting to the Microsoft Exchange data source. |
| secretArn | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Exchange data source. This includes your client ID and your client secret. |
| tenantId | The Microsoft 365 tenant ID (UUID v4 format). You can find your tenant ID in the Properties of your Azure Active Directory Portal. |
| dataEntityConfiguration | Configuration for the types of data entities to crawl from Microsoft Exchange. |
| filterConfiguration | Optional configuration for filtering content during the crawl process. |
| startDateFilter | Specify the start date for filtering emails. Only emails created on or after this date will be crawled. Format: ISO 8601 date-time (e.g., 2025-06-01T00:00:00Z). |
| endDateFilter | Specify the end date for filtering emails. Only emails created on or before this date will be crawled. Format: ISO 8601 date-time (e.g., 2025-07-01T00:00:00Z). |
| deletionProtectionConfiguration | Optional configuration to protect against accidental deletion of large amounts of content. |
| enableDeletionProtection | A Boolean value to enable deletion protection. When enabled, the connector will not delete more than the specified threshold of documents in a single sync. |
| deletionProtectionThreshold | The maximum percentage of documents that can be deleted in a single sync when deletion protection is enabled. Must be a string representing a number from 1-100 (e.g., "10" for 10%). |
## Sample configuration for the new Microsoft Exchange connector
The following is a sample configuration for the new Microsoft Exchange connector:
```
{
"displayName": "mail-0910-sample",
"configuration": {
"connectionConfiguration": {
"secretArn": "arn:aws:secretsmanager:{
"clientID": "OAuth Client ID",
"password": "client secret"
} |
| additionalProperties | Additional configuration options for your content in your data source. |
| isCrawlAcl | Specify true to crawl access control information from documents. Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. |
| fieldForUserId | Specify field to use for UserId for ACL crawling. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/onedrive-v1-api.html) | A collection of strings that specifies which entities to filter. |
| isUserNameOnS3 | true to provide a list of user names in a file stored in an Amazon S3. |
| type | The type of data source. Specify ONEDRIVE as your data source type. |
| enableIdentityCrawler | true to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). |
| maxFileSizeInMegaBytes | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/onedrive-v1-api.html) |
| version | The version of this template that's currently supported (1.0.0). |
# How Amazon Q Business connector crawls Microsoft OneDrive ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
The Microsoft OneDrive connector for Amazon Q Business crawls files, including documents, spreadsheets, presentations, and notes, as the primary content type. It supports various file formats and integrates directly with Microsoft Office apps.
**Roles/permissions**: The Microsoft OneDrive connector translates Microsoft OneDrive permissions into ACLs that are compatible with Amazon Q Business. The basic permissions include:
+ Read-only Access: users can view
+ Preview Access: users can view but cannot download
+ Edit: users can modify content
**Permission Inheritance**: The Microsoft OneDrive connector is designed to detect and handle hierarchical content organization. In Microsoft OneDrive files and subfolders inherit permissions from parent folders by default. Permissions can be customized at sub-folder and file levels. In this case, the ACLs are a union of the parent ACLs and child ACLs.
**Identity Crawling**: Individual user and group synchronization is supported, including federated groups. Users and groups are synced using email IDs (each group in Active Directory will have email assigned to it).
**Change Management**: ACL changes are supported in Change Log Mode, ensuring that items added, updated, or deleted since the last crawl are indexed. Any changes to access or permissions of groups or users for any entity will be captured.
**Failure handling**: The connector implements a fail-close approach, meaning that if there are permission-related issues or API failures, the document is skipped from ingestion rather than being made publicly accessible.
# Microsoft OneDrive data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved fields** – Mapped to reserved fields in the Amazon Q index that filter chat responses for your end users.
+ **Custom fields** – Mapped to custom fields in the Amazon Q index. You can create custom fields when you create your application or data source. You can use custom fields to provide additional information to help your end users.
For more information, see [Mapping data source fields](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/field-mappings.html).
The following table lists the Microsoft OneDrive data source connector entities and their associated attributes that you can map to Amazon Q index fields.
****
| Entity | Attributes | Field type |
| --- | --- | --- |
| File | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/onedrive-legacy-field-mappings.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/onedrive-legacy-field-mappings.html) |
# IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Error codes
The following table provides information about error codes you may see for the Microsoft OneDrive original connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| OND-5000 | Exception occurred while sending request to OneDrive api for testing connection, please try again later. | Try again. |
| OND-5001 | Provided client ID key is not Valid. | Provide a valid client ID. |
| OND-5002 | Provided client secret key is not valid. | Provide valid client secret. |
| OND-5003 | Provided tenant ID key is not valid. | Provide a valid tenant ID. |
| OND-5102 | Client ID cannot be null/empty. | Provide a valid client ID. |
| OND-5103 | Tenant ID cannot be null/empty. | Provide a valid tenant Id. |
| OND-5104 | Client Secret cannot be null/empty. | Provide a valid client Secret. |
| OND-5105 | Invalid client ID pattern. | Provide a valid client ID. |
| OND-5106 | Client Secret Over maximum length. | Length of client secret ID should be at least 256. Provide a valid client secret. |
| OND-5107 | User Name Filter/ User Name Path should not be null or empty value. | Provide User Name Filter or User Name Path. |
| OND-5108 | User Name Filter can only support up to 10 users. | Provide up to 10 users in User Name Filter or provide file of list of users in User Name Path. |
| OND-5109 | Users mentioned in the list do not belong to the same domain. | Provide valid list of users which belong to same domain. |
| OND-5110 | Users mentioned in the list are not valid. | Provide valid users. |
| OND-5200 | Exception occurred while fetching files in full crawl. | Check logs for more details. |
| OND-5203 | Exception occurred while fetching drive files. | Provide correct credentials. |
| OND-5204 | Exception occurred while fetching OneNote files. | Check logs for more details. |
| OND-5300 | Exception occurred while fetching files in change log. | Check logs for more details. |
| OND-5400 | Exception occurred while building group details. | Check logs for more details. |
| OND-5401 | Exception occurred while fetching list of groups. | Check logs for more details. |
| OND-5500 | Exception occurred while getting file content response. | Check logs for more details. |
| OND-5501 | Only String, String List, Date and Long formats are supported for field mappings. | Please provide valid formats in field mappings. |
| OND-5502 | Exception occurred while fetching OneNote files. | Check logs for more details. |
# Connecting SharePoint (Online) to Amazon Q Business
Microsoft SharePoint (Online)
Microsoft SharePoint is a collaborative website building service that lets you customize web content and create web pages, web sites, document libraries, and lists. You can connect SharePoint (Online) instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# Known limitations for the SharePoint (Online) connector
](sharepoint-cloud-limitations.md)
+ [
# SharePoint (Online) connector overview
](sharepoint-cloud-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to SharePoint (Online)
](sharepoint-cloud-prereqs.md)
+ [
# Connecting Amazon Q Business to SharePoint (Online) using the console
](sharepoint-cloud-console.md)
+ [
# Connecting Amazon Q Business to SharePoint (Online) using APIs
](sharepoint-cloud-api.md)
+ [
# Connecting Amazon Q Business to SharePoint (Online) using AWS CloudFormation
](sharepoint-cloud-cfn.md)
+ [
# How Amazon Q Business connector crawls SharePoint (Online) ACLs
](sharepoint-cloud-user-management.md)
+ [
# SharePoint (Online) data source connector field mappings
](sharepoint-cloud-field-mappings.md)
+ [
# IAM role for SharePoint (Online) connector
](sharepoint-cloud-iam-role.md)
+ [
# Understand error codes in the SharePoint (Online) connector
](sharepoint-cloud-error-codes.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the SharePoint (Online) connector
Known limitations
The SharePoint (Online) connector has the following known limitations:
+ The Amazon Q SharePoint (Online) connector supports custom field mappings only for the [https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-field-mappings.html#sharepoint-field-mappings-files](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-field-mappings.html#sharepoint-field-mappings-files) entity.
+ If an entity name has a `%` character in its name, the connector will skip these files due to API limitations.
+ OneNote can only be crawled by the connector using a Tenant ID, and with OAuth 2.0, OAuth 2.0 refresh token, or SharePoint (Online) App Only authentication activated for SharePoint (Online) Online.
+ The connector crawls the first section of a OneNote document using its default name only, even if the document is renamed.
+ The connector crawls event attachments only when **Events** is also selected as an entity to be crawled.
+ The User Principal Name in your Azure Portal is a combination of upper case and lower case, the SharePoint (Online) API internally converts it to lower case. Because of this, the Amazon Q SharePoint (Online) connector sets ACL in lower case.
For example, if **User principal name** is *MaryMajor@domain.com* in Azure portal, the ACL token in the SharePoint Connector will be *marymajor@domain.com*.
+ When Access Control Lists (ACLs) are enabled, the "Sync only new or modified content" option is not available due to SharePoint (Online) API limitations. We recommend using "Full sync" or "New, modified, or deleted content sync" modes instead, or disable ACLs if you need to use this sync mode.
+ If you want to crawl nested groups using **Identity crawler**, you have to activate Local as well as AD Group Crawling.
+ To use **Identity Crawler** with SharePoint (Online) to crawl nested groups, you have to enable both Local and AD Group Crawling.
+ Query responses based on AD Group ACLs are not supported for SharePoint (Online). You need to add users and groups directly to your document permissions list.
+ Microsoft requires granting the "Sites.FullControl.All" permission to the application in order to ingest the source ACLs from SharePoint
# SharePoint (Online) connector overview
Overview
The following table gives an overview of the Amazon Q Business SharePoint (Online) connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-overview.html)
# Prerequisites for connecting Amazon Q Business to SharePoint (Online)
Prerequisites
The following page outlines the prerequisites you need to complete before connecting SharePoint (Online) to Amazon Q, based on the authentication mode of your choice.
**Note**
For more information on connecting SharePoint (Online) to Amazon Q Business, see [Connect Amazon Q Business to Microsoft SharePoint Online using least privilege access controls](https://aws.amazon.com/blogs/machine-learning/connect-amazon-q-business-to-microsoft-sharepoint-online-using-least-privilege-access-controls/) and [Find answers accurately and quickly using Amazon Q Business with the SharePoint Online connector ](https://aws.amazon.com/blogs/machine-learning/find-answers-accurately-and-quickly-using-amazon-q-business-with-the-sharepoint-online-connector/) in the *AWS Machine Learning Blog*.
**Topics**
+ [
## Prerequisites for using Microsoft Entra ID (formerly Azure AD) App-Only authentication
](#sharepoint-cloud-prereqs-azure-app-only)
+ [
## Prerequisites for using OAuth 2.0 authentication
](#sharepoint-cloud-prereqs-oauth)
+ [
## Prerequisites for using SharePoint App-Only authentication
](#sharepoint-cloud-prereqs-sharepoint-app-only)
+ [
## Prerequisites for using basic authentication
](#sharepoint-cloud-prereqs-basic)
## Prerequisites for using Microsoft Entra ID (formerly Azure AD) App-Only authentication
**If you're using Microsoft Entra ID (formerly Azure AD) App-Only authentication, make sure you've completed the following steps in SharePoint (Online):**
+ Copied your SharePoint (Online) instance URLs. The format for the host URL you enter is *https://yourdomain.sharepoint.com/sites/mysite* or *https://yourcompany.sharepoint.com*. Your URL must start with `https` and contain `sharepoint.com`.
+ Copied the domain name of your SharePoint (Online) instance URL.
+ Copied the tenant ID of your Microsoft SharePoint (Online) instance. For details on how to find your tenant ID, see [Find your Microsoft 365 tenant ID](https://learn.microsoft.com/en-us/sharepoint/find-your-office-365-tenant-id) on the Microsoft website.
+ Generated an X.509 certificate. For more information on how to create and configure an X.509 certificate, see [Granting access via Microsoft Entra ID (formerly Azure AD) App-Only](https://learn.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azuread) and [New-PnPAzureCertificate](https://pnp.github.io/powershell/cmdlets/New-PnPAzureCertificate.html) in *Microsoft developer documentation*.
+ After generating the X.509 certificate, upload your .CRT file (the public certificate) to an Amazon S3 bucket. Note the file path to a X.509 certificate you have created and stored in an Amazon S3 bucket. (Ex. `s3://bucket-name/path/to/certificate.crt`). Ensure that your Amazon Q Business IAM role has permissions to read from this Amazon S3 bucket.
+ Noted the private key and the Client ID you generated after SharePoint (Online) Azure App registration.
+ Configured a Sharepoint (Online) Azure App using one of the two options below and noted its Client ID and Client secret.
**Note**
If you want to crawl specific sites, you can choose to restrict permissions to specific sites rather than all sites available in the domain. To do this, use the Sites.Selected (Application) permission. With this API permission, you need to set access permission on every site explicitly through the Microsoft Graph API. For more information, see [Microsoft's blog on Sites.Selected permissions](https://techcommunity.microsoft.com/t5/microsoft-sharepoint-blog/develop-applications-that-use-sites-selected-permissions-for-spo/ba-p/3790476).
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your SharePoint (Online) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
*Microsoft Entra ID (formerly Azure AD) App-Only Option 1: Global Read Access*
If you anticipate that you will be indexing several Sharepoint sites and would like to simplify your setup process, you can take the following steps to provide the Q Business Sharepoint connector global access. Otherwise, skip to section 2 below.
1. Create a Sharepoint client app to which we will assign the permissions needed by your Q Business connector. To register the app:
1. Log in to the Azure Portal with your Microsoft account.
1.
1. Provide the name for your application. In the example we are using the name TargetApp. The Amazon Q Business application uses TargetApp to connect to the SharePoint Online site to crawl and index the data.
1. Choose "Accounts" in the organizational directory. (Tenant name only - Single tenant).
1. Choose "Register".
1. Note down the application (client ID and the directory (tenant) on the Overview page, as you'll need them when prompted for "TargetApp-ClientId" and "TenantId".
1. Navigate to "Manage > API Permissions" in the navigation pane
1. Navigate to "Add a permission > Sharepoint > Application permissions" to allow the application to read data in your organization's directory regarding the signed-in user.
1. Search "AllSites.Read".
1. Choose "Add permissions".
1. Navigate to "Add a permission > Microsoft Graph > Application permissions"
1. Search and add the following permissions:
+ "Notes.Read.All"
+ "Sites.Read.All"
+ "Sites.FullControl.All (Application)" (required only if you intend to enable ACLs)
+ "Sites.Read.All (Application)"(required only if you intend to enable ACLs)
+ "Sites.FullControl.All" (required only if you intend to enable ACLs)
+ "GroupMember.Read.All" (required only if you intend to enable ACLs)
+ "User.Read.All" (required only if you intend to enable ACLs)
1. Navigate to "Remove permission"
1. Remove the original "User.Read - Delegated" permission
1. Choose "Grant admin consent" for the default directory
1. Save the client ID generated from this app for when you configure the Sharepoint connector in the Q Business console or API
The following tables summarize all the permissions your application should have.
+ If you're not using ACL, your application should have the permission:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-prereqs.html)
**Note**
Read.All and Sites.Read.All are required only if you want to crawl OneNote Documents.
+ If you're using ACL, your application should have the following permissions:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-prereqs.html)
1. Create a client secret for your Sharepoint App:
1. Within your client App navigate to "Clients and secrets > Client secrets"
1. Click on create a new secret.
1. Generate a new Certificate to be shared between Q Business SharePoint Connector and Microsoft Entra ID (formerly Azure AD) App:
1. Use the example command below to generate your own x509 certificate.
1. Run the following command:`openssl req -x509 -newkey rsa:2048 -noenc -sha1 -keyout /tmp/private.key -out /tmp/sharepoint.crt -nodes -set_serial 1 -days 365 -subj "/CN=amazon/emailAddress=example@aws.com/C=US/ST=Texas/L=Dallas/O=amazon/OU=amazon`
1. Save the generated private key located in /tmp/private.key for later when you configure the Q Business Sharepoint connector via the Q Business console or API.
*Microsoft Entra ID (formerly Azure AD) App-Only Option 2: Read Access for only Selected Sites*
If you anticipate that you will be indexing a manageable number of Sharepoint sites and would prefer to limit the permissions of the Q Business connector to just the Sharepoint sites you intend to index, you can take the following steps:
1. Create a Sharepoint client app: Create a Sharepoint client app to which we will assign the permissions needed by your Q Business connector. To register the app:
1. Log in to the Azure Portal with your Microsoft account.
1. Choose "New Registration":
1. Provide the name for your application. In the example we are using the name TargetApp. The Amazon Q Business application uses TargetApp to connect to the SharePoint Online site to crawl and index the data.
1. Choose "Accounts" in the organizational directory. (Tenant name only - Single tenant).
1. Choose "Register".
1. Note down the application (client ID and the directory (tenant) on the Overview page, as you'll need them when prompted for "TargetApp-ClientId" and "TenantId".
1. Navigate to "Manage > API Permissions" in the navigation pane
1. Navigate to "Add a permission > Sharepoint > Application permissions" to allow the application to read data in your organization's directory regarding the signed-in user.
1. Search "Sites.Selected".
1. Choose "Add permissions".
1. Navigate to "Add a permission > Microsoft Graph > Application permissions"
1. Search and add the following permissions:
+ "Notes.Read.All"
+ "Sites.Selected"
+ "GroupMember.Read.All" (required only if you intend to enable ACLs)
+ "User.Read.All" (required only if you intend to enable ACLs)
1. Navigate to "Remove permission"
1. Remove the original "User.Read - Delegated" permission
1. Choose "Grant admin consent" for the default directory
1. Save the client ID generated from this app for when you configure the Sharepoint connector in the Q Business console or API
The following tables summarize all the permissions your application should have.
+ If you're not using ACL, your application should have the permissions:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-prereqs.html)
**Note**
Read.All and Sites.Read.All are required only if you want to crawl OneNote Documents.
+ If you're using ACL, your application should have the following permissions:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-prereqs.html)
1. Create a client secret for your Sharepoint App:
1. Within your client App navigate to "Clients and secrets > Client secrets"
1. Click on create a new secret.
1. Generate a new Certificate to be shared between Q Business SharePoint Connector and Microsoft Entra ID (formerly Azure AD) App:
1. Run the following command: `openssl req -x509 -newkey rsa:2048 -noenc -sha1 -keyout /tmp/private.key -out /tmp/sharepoint.crt -nodes -set_serial 1 -days 365 -subj "/CN=amazon/emailAddress=example@aws.com/C=US/ST=Texas/L=Dallas/O=amazon/OU=amazon"`
1. Save the generated private key located in /tmp/private.key for later when you configure the Q Business Sharepoint connector via the Q Business console or API.
1. Upload the generated certificate located in /tmp/sharepoint.crt to an S3 bucket so you can use it later when you configure the Q Business Sharepoint connector via the Q Business console or API. You will also need this certificate for the next step.
1. Update your Sharepoint Client App’s Certificate:
1. Navigate to the Sharepoint client app you created in step 1.
1. Navigate to “Certificates and secrets > Certificates > Upload certificate” and upload the certificate (.crt file) you generated in step 4.
1. Create a Sharepoint admin app: This app will be used to provide the necessary site read permissions for the client OAuth App you created in the previous step. You can delete this admin app after you have completed all the steps. To register the app:
1. Log in to the Azure Portal with your Microsoft account.
1. Choose “New Registration”:
1. Provide the name for your application.
1. Choose "Accounts" in the organizational directory. (Tenant name only - Single tenant).
1. Choose "Register".
1. Locate your app ID, app secret, and tenant ID for your admin app and save them for the next step.
1. Navigate to "Manage > API Permissions" in the navigation pane
1. Navigate to "Add a permission > Sharepoint > Application permissions" to allow the application to read data in your organization's directory regarding the signed-in user.
1. Search "Sites.FullControl.All".
1. Choose "Add permissions".
1. Navigate to "Add a permission > Microsoft Graph > Application permissions"
1. Search "Sites.Read.All".
1. Choose "Add permissions".
1. Generate an access token for your Sharepoint admin app: Now use the following code snippet to generate an access token for your app, but replace adminAppID, adminAppSecret, and tenantID with the values you saved from step 2.
1.
```
adminAppId=$1
adminAppSecret=$2
tenantId=$3
tokenResponse=$(curl -s --location \
"https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=$adminAppId" \
--data-urlencode "client_secret=$adminAppSecret" \
--data-urlencode "scope=offline_access https://graph.microsoft.com/.default")
adminAppToken=$(echo $tokenResponse | jq -r '.access_token')
echo $adminAppToken
```
1. Obtain a Site ID for each of your Sharepoint sites: Repeat the following steps for each of the Sharepoint sites you want your Q Business connector to crawl:
1. Visit `https://{yourcompany}.sharepoint.com/sites/{SiteName}`in a browser. Enter the appropriate login credentials if needed. Validate that you are able to see your SharePoint site
1. Now append /\$1api/site/id at the end of \$1SiteName\$1. You should see a response something similar to below containing your site id (96a47524-4b21-446f-bf96-96d2f6fe4aa7)
```
{
"username": "SharePoint (Online) account user name",
"password": "SharePoint (Online) password"
}If you use Azure AD App-only authentication (authType should be OAuth2Certificate), the secret must contain a JSON structure with the following keys: {
"clientId": "SharePoint (Online) client ID",
"privateKey": "SharePoint (Online) private key"
}If you use OAuth2 authentication (authType should be OAuth) or Sharepoint App-Only authentication (authType should be OAuth2App) the secret must contain a JSON structure with the following keys: {
"clientId": "SharePoint (Online) client ID",
"clientSecret": "SharePoint (Online) client secret",
"userName": "SharePoint (Online) account user name",
"password": "SharePoint (Online) password"
} | Yes |
| `version` | The version of this template that's currently supported. | `string` | No |
## SharePoint (Online) JSON schema
The following is the SharePoint (Online) JSON schema:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["SHAREPOINTV2", "SHAREPOINT"]
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"minLength": 36,
"maxLength": 36
},
"domain": {
"type": "string"
},
"siteUrls": {
"type": "array",
"items": {
"type": "string",
"pattern": "https://.*"
}
},
"repositoryAdditionalProperties": {
"type": "object",
"properties": {
"s3bucketName": {
"type": "string"
},
"s3certificateName": {
"type": "string"
},
"authType": {
"type": "string",
"enum": [
"OAuth2",
"OAuth2Certificate",
"OAuth2App",
"Basic"
]
},
"version": {
"type": "string",
"enum": ["Online"]
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": ["authType", "version"]
}
},
"required": ["siteUrls", "domain", "repositoryAdditionalProperties"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"event": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"page": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"file": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"link": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"eventTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"pageTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"linkTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"crawlFiles": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPages": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlEvents": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlComments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlLinks": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAttachments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlListData": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlLocalGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlAdGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"type",
"syncMode",
"secretArn",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
## SharePoint (Online) JSON schema example
The following is the SharePoint (Online) JSON schema example:
```
{
"type": "SHAREPOINTV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-sharepoint-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"tenantId": "1234567a-890b-1234-567c-123456789012",
"domain": "example.sharepoint.com",
"siteUrls": ["https://example.sharepoint.com/sites/mysite"],
"repositoryAdditionalProperties": {
"s3bucketName": "my-bucket",
"s3certificateName": "my-certificate",
"authType": "OAuth2",
"version": "Online",
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
},
"repositoryConfigurations": {
"event": {
"fieldMappings": [
{
"indexFieldName": "event_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"page": {
"fieldMappings": [
{
"indexFieldName": "page_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"eventTitleFilterRegEx": ["^.*$"],
"pageTitleFilterRegEx": ["^.*$"],
"linkTitleFilterRegEx": ["^.*$"],
"inclusionFilePath": ["documents/"],
"exclusionFilePath": ["drafts/"],
"inclusionFileTypePatterns": ["*.docx"],
"exclusionFileTypePatterns": ["*.tmp"],
"inclusionFileNamePatterns": ["*report*"],
"exclusionFileNamePatterns": ["*draft*"],
"enableDeletionProtection": "false",
"maxFileSizeInMegaBytes": "50"
}
}
```
# Connecting Amazon Q Business to SharePoint (Online) using AWS CloudFormation
Using the CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
**Topics**
+ [
## SharePoint (Online) configuration properties
](#sharepoint-cloud-configuration-keys)
+ [
## SharePoint (Online) JSON schema for using the configuration property with AWS CloudFormation
](#sharepoint-cloud-cfn-json)
+ [
## SharePoint (Online) YAML schema for using the configuration property with AWS CloudFormation
](#sharepoint-cloud-cfn-yaml)
## SharePoint (Online) configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has a sub-property called `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | Yes |
| `tenantId` | The tenant id of your SharePoint (Online) account. | `string` OAuth2 series required | Yes |
| `domain` | The domain of your SharePoint (Online) account. | `string` | Yes |
| `siteUrls` | The host URLs of your SharePoint (Online) account. | `array (string)` Specify the URL in the pattern `https://*` | Yes |
| `repositoryAdditionalProperties` | Additional properties to connect with your repository endpoint. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | Yes |
| `s3bucketName` | The name of the Amazon S3 bucket that stores your Azure AD self-signed X.509 certificate. | `string` Azure AD App-Only auth required | No |
| `s3certificateName` | The name of the SSL certificate stored in your Amazon S3 bucket. | `string` Azure AD App-Only auth required | No |
| `authType` | The type of authentication you are using: OAuth2, OAuth2Certificate, OAuth2App, or Basic. | `string` | Yes |
| `version` | The SharePoint version you are using: Online. | `string (Online)` Azure AD App-Only auth required | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | A list of objects that map the attributes or field names of your SharePoint (Online) pages and assets to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | No |
| `indexFieldName` | The field name of your SharePoint (Online) events, pages, files, links, attachments, or comments. | `string` | Yes |
| `indexFieldType` | The field type of your SharePoint (Online) events, pages, files, links, attachments, or comments. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your SharePoint (Online) events, pages, files, links, attachments, or comments. | `string` | Yes |
| `dateFieldFormat` | The date format of your SharePoint (Online) events, pages, files, links, attachments, or comments. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | A list of regular expression patterns to include/exclude specific files in your SharePoint (Online) data source. Files that match the patterns are included in the index. File that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | Input TRUE to index. | `boolean` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| `type` | We recommend that you use SHAREPOINTV2 as your data source type | `string` Valid values are `SHAREPOINTV2` and `SHAREPOINT`. | Yes |
| `enableIdentityCrawler` | `true` to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). | `boolean` | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-cloud-cfn.html) | Yes |
| `secretARN` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your SharePoint. If you use basic authentication, provide the username and password. If you use OAuth 2.0 authentication, provide the username, password, client ID, and client secret. | `string` The minimum length is 20 and the maximum length is 2,048 characters. If you use basic authentication (authType should be Basic), the secret must contain a JSON structure with the following keys: {
"username": "SharePoint (Online) account user name",
"password": "SharePoint (Online) password"
}If you use Azure AD App-only authentication (authType should be OAuth2Certificate), the secret must contain a JSON structure with the following keys: {
"clientId": "SharePoint (Online) client ID",
"privateKey": "SharePoint (Online) private key"
}If you use OAuth2 authentication (authType should be OAuth) or Sharepoint App-Only authentication (authType should be OAuth2App) the secret must contain a JSON structure with the following keys: {
"clientId": "SharePoint (Online) client ID",
"clientSecret": "SharePoint (Online) client secret",
"userName": "SharePoint (Online) account user name",
"password": "SharePoint (Online) password"
} | Yes |
| `version` | The version of this template that's currently supported. | `string` | No |
## SharePoint (Online) JSON schema for using the configuration property with AWS CloudFormation
SharePoint (Online) JSON schema
The following is the SharePoint (Online) JSON schema and examples for the configuration property for AWS CloudFormation.
**Topics**
+ [
### SharePoint (Online) JSON schema for using the configuration property with AWS CloudFormation
](#sharepoint-cloud-cfn-json-schema)
+ [
### SharePoint (Online) JSON schema example for using the configuration property with AWS CloudFormation
](#sharepoint-cloud-cfn-json-example)
### SharePoint (Online) JSON schema for using the configuration property with AWS CloudFormation
SharePoint (Online) JSON schema
The following is the SharePoint (Online) JSON schema for the configuration property for CloudFormation
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["SHAREPOINTV2", "SHAREPOINT"]
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"minLength": 36,
"maxLength": 36
},
"domain": {
"type": "string"
},
"siteUrls": {
"type": "array",
"items": {
"type": "string",
"pattern": "https://.*"
}
},
"repositoryAdditionalProperties": {
"type": "object",
"properties": {
"s3bucketName": {
"type": "string"
},
"s3certificateName": {
"type": "string"
},
"authType": {
"type": "string",
"enum": [
"OAuth2",
"OAuth2Certificate",
"OAuth2App",
"OAuth2_RefreshToken",
"Basic"
]
},
"version": {
"type": "string",
"enum": ["Online"]
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": ["authType", "version"]
}
},
"required": ["siteUrls", "domain", "repositoryAdditionalProperties"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"event": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"page": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"file": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"link": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"eventTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"pageTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"linkTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"crawlFiles": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPages": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlEvents": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlComments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlLinks": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAttachments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlListData": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"aclConfiguration": {
"type": "string",
"enum": [
"ACLWithLDAPEmailFmt",
"ACLWithManualEmailFmt",
"ACLWithUsernameFmt"
]
},
"emailDomain": {
"type": "string"
},
"isCrawlLocalGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlAdGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"type",
"syncMode",
"secretArn",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
### SharePoint (Online) JSON schema example for using the configuration property with AWS CloudFormation
SharePoint (Online) JSON schema example
The following is the SharePoint (Online) JSON schema example for the configuration property for CloudFormation
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "CloudFormation SHAREPOINT Data Source Template",
"Resources": {
"DataSourceSharePoint": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": "app12345-1234-1234-1234-123456789012",
"IndexId": "indx1234-1234-1234-1234-123456789012",
"DisplayName": "MySharePointDataSource",
"RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role",
"Configuration": {
"type": "SHAREPOINTV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-sharepoint-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"tenantId": "1234567a-890b-1234-567c-123456789012",
"domain": "example.sharepoint.com",
"siteUrls": ["https://example.sharepoint.com/sites/mysite"],
"repositoryAdditionalProperties": {
"s3bucketName": "my-bucket",
"s3certificateName": "my-certificate",
"authType": "OAuth2",
"version": "Online",
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
},
"repositoryConfigurations": {
"event": {
"fieldMappings": [
{
"indexFieldName": "event_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"page": {
"fieldMappings": [
{
"indexFieldName": "page_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"eventTitleFilterRegEx": ["^.*$"],
"pageTitleFilterRegEx": ["^.*$"],
"linkTitleFilterRegEx": ["^.*$"],
"inclusionFilePath": ["documents/"],
"exclusionFilePath": ["drafts/"],
"inclusionFileTypePatterns": ["\\.docx"],
"exclusionFileTypePatterns": ["\\.tmp"],
"inclusionFileNamePatterns": ["*report*"],
"exclusionFileNamePatterns": ["*draft*"],
"enableDeletionProtection": "false",
"maxFileSizeInMegaBytes": "50"
}
}
}
}
}
}
```
## SharePoint (Online) YAML schema for using the configuration property with AWS CloudFormation
SharePoint (Online) YAML schema
The following is the SharePoint (Online) YAML schema and examples for the configuration property for AWS CloudFormation:
**Topics**
+ [
### SharePoint (Online) YAML schema for using the configuration property with AWS CloudFormation
](#sharepoint-cloud-cfn-yaml-schema)
+ [
### SharePoint (Online) YAML schema example for using the configuration property with AWS CloudFormation
](#sharepoint-cloud-cfn-yaml-example)
### SharePoint (Online) YAML schema for using the configuration property with AWS CloudFormation
SharePoint (Online) YAML schema
The following is the SharePoint (Online) YAML schema for the configuration property for CloudFormation.
```
$schema: http://json-schema.org/draft-04/schema#
type: object
properties:
type:
type: string
enum:
- SHAREPOINTV2
- SHAREPOINT
syncMode:
type: string
enum:
- FULL_CRAWL
- FORCED_FULL_CRAWL
- CHANGE_LOG
secretArn:
type: string
minLength: 20
maxLength: 2048
enableIdentityCrawler:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
connectionConfiguration:
type: object
properties:
repositoryEndpointMetadata:
type: object
properties:
tenantId:
type: string
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
minLength: 36
maxLength: 36
domain:
type: string
siteUrls:
type: array
items:
type: string
pattern: "https://.*"
repositoryAdditionalProperties:
type: object
properties:
s3bucketName:
type: string
s3certificateName:
type: string
authType:
type: string
enum:
- OAuth2
- OAuth2Certificate
- OAuth2App
- OAuth2_RefreshToken
- Basic
version:
type: string
enum:
- Online
enableDeletionProtection:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
default: false
deletionProtectionThreshold:
type: string
default: "15"
required:
- authType
- version
required:
- siteUrls
- domain
- repositoryAdditionalProperties
required:
- repositoryEndpointMetadata
repositoryConfigurations:
type: object
properties:
event:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
page:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
file:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
link:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
attachment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
comment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
required: []
additionalProperties:
type: object
properties:
eventTitleFilterRegEx:
type: array
items:
type: string
pageTitleFilterRegEx:
type: array
items:
type: string
linkTitleFilterRegEx:
type: array
items:
type: string
inclusionFilePath:
type: array
items:
type: string
exclusionFilePath:
type: array
items:
type: string
inclusionFileTypePatterns:
type: array
items:
type: string
exclusionFileTypePatterns:
type: array
items:
type: string
inclusionFileNamePatterns:
type: array
items:
type: string
exclusionFileNamePatterns:
type: array
items:
type: string
inclusionOneNoteSectionNamePatterns:
type: array
items:
type: string
exclusionOneNoteSectionNamePatterns:
type: array
items:
type: string
inclusionOneNotePageNamePatterns:
type: array
items:
type: string
exclusionOneNotePageNamePatterns:
type: array
items:
type: string
crawlFiles:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlPages:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlEvents:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlComments:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlLinks:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlAttachments:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlListData:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlAcl:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
aclConfiguration:
type: string
enum:
- ACLWithLDAPEmailFmt
- ACLWithManualEmailFmt
- ACLWithUsernameFmt
emailDomain:
type: string
isCrawlLocalGroupMapping:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
isCrawlAdGroupMapping:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
maxFileSizeInMegaBytes:
type: string
required: []
version:
type: string
anyOf:
- pattern: 1.0.0
required:
- type
- syncMode
- secretArn
- enableIdentityCrawler
- connectionConfiguration
- repositoryConfigurations
- additionalProperties
```
### SharePoint (Online) YAML schema example for using the configuration property with AWS CloudFormation
SharePoint (Online) JSON schema example
The following is the SharePoint (Online) YAML example for the Configuration property for CloudFormation:
```
AWSTemplateFormatVersion: "2010-09-09"
Description: CloudFormation SHAREPOINT Data Source Template
Resources:
DataSourceSharePoint:
Type: AWS::QBusiness::DataSource
Properties:
ApplicationId: app12345-1234-1234-1234-123456789012
IndexId: indx1234-1234-1234-1234-123456789012
DisplayName: MySharePointDataSource
RoleArn: arn:aws:iam::123456789012:role/qbusiness-data-source-role
Configuration:
type: SHAREPOINTV2
syncMode: FULL_CRAWL
secretArn: arn:aws:secretsmanager:us-west-2:123456789012:secret:my-sharepoint-secret
enableIdentityCrawler: "true"
connectionConfiguration:
repositoryEndpointMetadata:
tenantId: 1234567a-890b-1234-567c-123456789012
domain: example.sharepoint.com
siteUrls:
- https://example.sharepoint.com/sites/mysite
repositoryAdditionalProperties:
s3bucketName: my-bucket
s3certificateName: my-certificate
authType: OAuth2
version: Online
enableDeletionProtection: "false"
deletionProtectionThreshold: "15"
repositoryConfigurations:
event:
fieldMappings:
- indexFieldName: event_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
page:
fieldMappings:
- indexFieldName: page_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
additionalProperties:
eventTitleFilterRegEx:
- "^.*$"
pageTitleFilterRegEx:
- "^.*$"
linkTitleFilterRegEx:
- "^.*$"
inclusionFilePath:
- documents/
exclusionFilePath:
- drafts/
inclusionFileTypePatterns:
- ".docx"
exclusionFileTypePatterns:
- ".tmp"
inclusionFileNamePatterns:
- "*report*"
exclusionFileNamePatterns:
- "*draft*"
enableDeletionProtection: "false"
maxFileSizeInMegaBytes: "50"
```
# How Amazon Q Business connector crawls SharePoint (Online) ACLs
ACL crawling
When you connect an SharePoint (Online) data source to Amazon Q Business, Amazon Q crawls ACL information attached to a document (user and group information) from your SharePoint (Online) instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
To filter using a username, use the **User principal name** from your Azure portal. For example, johnstiles@amazonq.onmicrosoft.com.
When you use a SharePoint group for user context filtering, calculate the group ID as follows:
**For local groups**
1. Get the site name. For example, `https://host.onmicrosoft.com/sites/siteName.`
1. Take the SHA256 hash of the site name. For example, `430a6b90503eef95c89295c8999c7981`.
1. Create the group ID by concatenating the SHA256 hash with a vertical bar ( \$1 ) and the group name. For example, if the group name is "local group name", the group ID is the following:
`"430a6b90503eef95c89295c8999c7981 | localGroupName"` (with a space before and after the vertical bar).
**For Microsoft Entra ID (formerly Azure AD) groups**
1. You must integrate the Microsoft Entra ID (formerly Azure AD) with Amazon Identity Center and use the same group name present on Azure portal.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# SharePoint (Online) data source connector field mappings
Field mappings
To help you structure data for retrieval and chat filtering, Amazon Q Business crawls data source document attributes or metadata and maps them to fields in your Amazon Q index.
Amazon Q has reserved fields that it uses when querying your application. When possible, Amazon Q automatically maps these built-in fields to attributes in your data source. If a built-in field doesn't have a default mapping, or if you want to map additional index fields, use the custom field mappings to specify how a data source attribute maps to your Amazon Q application. You create field mappings by editing your data source after your application environment and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Sharepoint connector supports the following entities and the associated reserved and custom attributes.
**Important**
If you map any SharePoint (Online) field to Amazon Q document title and document body fields, Amazon Q will generate responses from data in the document title and body.
**Note**
You can map any Sharepoint field to the document title or document body Amazon Q reserved/default index fields.
**Topics**
+ [
## Files
](#sharepoint-field-mappings-files)
+ [
## Events
](#sharepoint-field-mappings-events)
+ [
## Pages
](#sharepoint-field-mappings-pages)
+ [
## Links
](#sharepoint-field-mappings-links)
+ [
## Attachments
](#sharepoint-field-mappings-attachments)
+ [
## Comments
](#sharepoint-field-mappings-comments)
## Files
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | sp\$1title | Custom | String |
| sourceUri | \$1source\$1uri | Default | String |
| checkInComment | sp\$1checkInComment | Custom | String |
| size | sp\$1sizeLong | Custom | Long (numeric) |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| createdAt | \$1created\$1at | Default | Date |
| author | \$1authors | Default | String list |
| majorVersion | sp\$1majorVersion | Custom | String |
| uiVersionLabel | sp\$1uiVersionLabel | Custom | String |
| uniqueId | sp\$1uniqueId | Custom | String |
| irmEnabled | sp\$1irmEnabled | Custom | String |
| checkOutType | sp\$1checkOutType | Custom | String |
| category | \$1category | Default | String |
| modifiedBy | sp\$1modifiedBy | Custom | String |
| level | sp\$1level | Custom | String |
| uiVersion | sp\$1uiVersion | Custom | String |
| contentTag | sp\$1contentTag | Custom | String |
| eTag | sp\$1eTag | Custom | String |
| oneNoteDocument | sp\$1oneNoteDocument | Custom | String |
| oneNoteSection | sp\$1oneNoteSection | Custom | String |
| oneNotePage | sp\$1oneNotePage | Custom | String |
## Events
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | sp\$1title | Custom | String |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| sourceUri | \$1source\$1uri | Default | String |
| attachments | sp\$1hasAttachments | Custom | String |
| createdDate | \$1created\$1at | Default | Date |
| authorId | sp\$1authorId | Custom | String |
| editorId | sp\$1editorId | Custom | String |
| location | sp\$1location | Custom | String |
| eventDate | sp\$1eventDate | Custom | Date |
| eventEndDate | sp\$1eventEndDate | Custom | Date |
| ifRecurrence | sp\$1ifRecurrence | Custom | String |
| ifAllDayEvent | sp\$1ifAllDayEvent | Custom | String |
| category | \$1category | Default | String |
| eventCategory | sp\$1eventcategory | Custom | String |
## Pages
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| createdDateTime | \$1created\$1at | Default | Date |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| title | sp\$1title | Custom | String |
| sourceUri | \$1source\$1uri | Default | String |
| firstPublishedDate | sp\$1firstPublishedDate | Custom | Date |
| authorId | sp\$1authorId | Custom | String |
| editorId | sp\$1editorId | Custom | String |
| category | \$1category | Default | String |
## Links
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| createdAt | \$1created\$1at | Default | Date |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| title | sp\$1title | Custom | String |
| sourceUri | \$1source\$1uri | Default | String |
| fileType | sp\$1fileType | Custom | String |
| fileDirPath | sp\$1fileDirPath | Custom | String |
| firstPublishedDate | sp\$1firstPublishedDate | Custom | Date |
| authorId | sp\$1authorId | Custom | String |
| editorId | sp\$1editorId | Custom | String |
| category | \$1category | Default | String |
| size | sp\$1sizeLong | Custom | Long (numeric) |
## Attachments
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | sp\$1\$1title | Custom | String |
| parentCreatedDate | \$1created\$1at | Default | Date |
| sourceUri | \$1source\$1uri | Default | String |
| parentModifiedDate | \$1last\$1updated\$1at | Custom | Date |
| parentListId | sp\$1parentListId | Custom | String |
| parentTitle | sp\$1parentTitle | Custom | String |
| category | \$1category | Default | String |
## Comments
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| createdDateTime | \$1created\$1at | Default | Date |
| likedBy | sp\$1likedBy | Custom | String |
| sourceUri | \$1source\$1uri | Custom | String |
| isReply | sp\$1isReply | Custom | String |
| author | \$1authors | Default | String list |
| listId | sp\$1listId | Custom | String |
| category | \$1category | Default | String |
| replyCount | sp\$1replyCount | Custom | String |
| parentTitle | sp\$1parentTitle | Custom | String |
# IAM role for SharePoint (Online) connector
IAM role
**Note**
**(Optional)** If you use **Azure App-Only authentication**, you also need to add permissions for Amazon Q to access the certificate stored in your Amazon S3 bucket.
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
**To ensure that Amazon Q Business is able to access Amazon S3 you objects:**
If you are using Microsoft Entra ID (formerly Azure AD) App only authentication, you must ensure that Amazon Q Business is able access Amazon S3 to get the objects in your bucket. The following policy statement is provides permissions to access Amazon S3:
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
}
]
}
```
**If using a VPC:**
If you are using a VPC, you must ensure that the permissions included in the following policy statement are included in your policy statement:
```
{
"Version": "2012-10-17", ,
"Statement": [
{
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
# Understand error codes in the SharePoint (Online) connector
Error Codes
The following table provides information about error codes you may see for the Microsoft SharePoint connector and suggested resolutions. If you used the Amazon Q section of the AWS [console](https://console.aws.amazon.com/console/home) to configure your connectors, be sure to make the changes associated with an error through the console as well. You can refer to the Microsoft SharePoint [documentation](https://learn.microsoft.com/en-us/sharepoint/) for more information regarding SharePoint settings and details.
**Authentication issues**
| Error code | Error message | Suggested resolution | Context | Where to find error |
| --- | --- | --- | --- | --- |
| SPE-5001 | Authentication failed. Configuration might contain wrong credentials. | Provide valid credentials like username, password or client Id, client secret and tenant Id. | Occurs during initial connector setup or when authentication credentials expire | Console: During configuration or Sync run history |
| SPE-5124 | There was a problem while retrieving authType. Auth-Type might be empty or null. | Ensure AUTH Type in configuration must be not null. | Authentication type configuration error | Console: Configuration page |
| SPE-5129 | There was a problem while retrieving password. Password might be empty or null. | Provide password. | Basic authentication configuration error | Console: During initial setup |
| SPE-5130 | There was a problem while retrieving username.Username might be empty or null. | Provide username. | Basic authentication configuration error | Console: During initial setup |
| SPE-5136 | The provided authType was not a valid Sharepoint Connector authentication method. | Provide valid authType. The value of authType should be one of [Basic, OAuth2Certificate, OAuth2]. | Authentication method configuration error | Console: Configuration page |
| SPE-5125 | There was a problem while retrieving clientId. Client ID might be empty or null. | Provide Client Id. | OAuth configuration error | Console: Authentication Configuration |
| SPE-5126 | There was a problem while retrieving clientSecret. Client Secret might be empty or null. | Provide Client Secret. | OAuth configuration error | Console: Authentication Configuration |
| SPE-5127 | There was a problem while retrieving tenantId. Tenant ID might be empty or null. | Provide Tenant Id. | SharePoint tenant configuration error | Console: Authentication Configuration |
**SharePoint Configuration issues**
| Error code | Error message | Suggested resolution | Context | Where to find error |
| --- | --- | --- | --- | --- |
| SPE-5135 | The provided version was not a valid Sharepoint Connector version. Version should be one of [Online, Server]. | Version should be one of [Online, Server]. | SharePoint version selection error | Console: During initial setup |
| SPE-5138 | There was a problem while retrieving onPremVersion. On prem Version might be empty or null | Ensure onPremVersion is not be null or non-empty. | SharePoint on-premises version error | Console: Version Configuration |
| SPE-5139 | The provided onPremVersion was not valid Sharepoint on-prem version. On prem version should be one of [2013, 2016, 2019, SubscriptionEdition]. | Provide a valid onPremVersion. On prem version should be one of [2013, 2016, 2019, SubscriptionEdition]. | SharePoint on-premises version selection error | Console: Version Configuration |
| SPE-5121 | There was a problem while retrieving values for crawl entities. Values might be empty or incorrect. It should be either true or false. | In the connector's settings, ensure all crawl options are set to either 'true' or 'false'. These settings determine what content types are indexed. | Crawler configuration error | Console: Crawl Configuration |
| SPE-5122 | There was a problem while retrieving domain. Domain might be empty or null. | Provide a valid SharePoint domain name in the connector configuration. | Domain configuration error during SharePoint connection setup. | Console: Domain Configuration |
| SPE-5123 | There was a problem while retrieving version. Version might be empty or null. | Provide valid version and it should not be null. | SharePoint version configuration error | Console: Version Configuration |
**Network and Connectivity issues**
| Error code | Error message | Suggested resolution | Context | Where to find error |
| --- | --- | --- | --- | --- |
| SPE-5004 | Inet Address validation Failed. | Check your network configuration and ensure the SharePoint server address is accessible from your network. Verify DNS resolution and network routing are properly configured. | Network address validation error | CloudWatch Logs during sync |
| SPE-5005 | Failed : HTTP protocol violation has occurred. | Try running the connector again. | Occurs when the connector is configured to use a proxy but cannot establish connection. | CloudWatch Logs during sync |
| SPE-5200 | There was a problem while connecting to the URL. | Verify that the SharePoint site URL is accessible and that you have proper network connectivity. Check SharePoint site status and your network configuration. | Site connectivity error | Console: Sync run history |
| SPE-5002 | SPE-5002 Connection failed due to wrong credentials or invalid sites. Update your configuration and try again. | Provide valid Host URL or Domain. | Happens during connector configuration when trying to establish initial connection | Console: Basic Configuration |
| SPE-5003 | Provided URL is incorrect | Provide correct URL. | Generic URL validation error | Console: Site Configuration |
**LDAP Configuration issues**
| Error code | Error message | Suggested resolution | Context | Where to find error |
| --- | --- | --- | --- | --- |
| SPE-5009 | There was a problem while connecting to LDAP. Check LDAP configuration. | Provide valid LDAP configuration details. | LDAP connection failure | Console: LDAP Configuration |
| SPE-5140 | There was a problem while retrieving ldapUrl. LDAP Url might be empty or null. | Ensure ldapUrl is not null or empty. | LDAP configuration error | Console: LDAP Configuration |
| SPE-5141 | There was a problem while retrieving baseDn. Base DN might be empty or null. | Ensure baseDn is not be null or empty. | LDAP configuration error | Console: LDAP Configuration |
| SPE-5146 | There was a problem while retrieving ldapUsername. LDAP Username might be empty or null. | Ensure ldapUser is not null or empty. | LDAP authentication error | Console: LDAP Configuration |
| SPE-5147 | There was a problem while retrieving ldapPassword. LDAP Password might be empty or null. | Ensure ldapPassword is not null or empty. | LDAP authentication error | Console: LDAP Configuration |
**Microsoft Entra ID (formerly Azure AD) Configuration issues**
| Error code | Error message | Suggested resolution | Context | Where to find error |
| --- | --- | --- | --- | --- |
| SPE-5152 | There was a problem while retrieving AD Client ID. AD Client ID should not be empty. | Ensure AD Client Id must be non-empty. | Microsoft Entra ID (formerly Azure AD) configuration error | Console: Microsoft Entra ID (formerly Azure AD) Configuration |
| SPE-5153 | Invalid AD Client Id pattern. | Provide valid AD Client Id pattern. | Microsoft Entra ID (formerly Azure AD) Client ID format error | Console: Microsoft Entra ID (formerly Azure AD) Configuration |
| SPE-5154 | There was a problem while retrieving AD Client Secret. AD Client Secret should not be empty. | Ensure AD Client Secret is non-empty. | Microsoft Entra ID (formerly Azure AD) configuration error | Console: Microsoft Entra ID (formerly Azure AD) Configuration |
**Document Access and Permissions issues**
| Error code | Error message | Suggested resolution | Context | Where to find error |
| --- | --- | --- | --- | --- |
| SPE-5144 | There was a problem while retrieving aclConfiguration. ACL Configuration might be empty, null or invalid | Provide valid aclConfiguration. aclConfiguration should be one of [ ACLWithLDAPEmailFmt, ACLWithManualEmailFmt, ACLWithUsernameFmt ]. | ACL configuration error | Console: Access Control Configuration |
| SPE-5145 | There was a problem while retrieving emailDomain. Email Domain might be empty or null. | Ensure emailDomain is not null or empty. | Email domain configuration error | Console: Domain Configuration |
| SPE-5155 | There can't be more than one site for SharePoint on-prem app-only authentication. | Ensure that their must be only single site present for SharePoint on-prem app-only authentication. | SharePoint on-premises app authentication configuration error | Console: Site Configuration |
**Security Configuration issues**
| Error code | Error message | Suggested resolution | Context | Where to find error |
| --- | --- | --- | --- | --- |
| SPE-5008 | Valid SSL Certificate could not be found for connector. | Upload a valid SSL certificate. For SharePoint on-premises installations, ensure you have exported your SharePoint SSL certificate and uploaded it to the connector. | SSL certificate validation failure | Console: Security Configuration |
**IAM Configuration issues**
| Error code | Error message | Suggested resolution | Context | Where to find error |
| --- | --- | --- | --- | --- |
| SPE-5101 | There was a problem while retrieving dataSourceIamRoleArn. Data Source IAM Role ARN might be empty or null. | Verify that the IAM role exists and has the correct permissions. Check the IAM console to ensure the role is properly configured. | This error occurs when the connector cannot access the required IAM role during synchronization. | Console: IAM Configuration |
**Site Configuration issues**
| Error code | Error message | Suggested resolution | Context | Where to find error |
| --- | --- | --- | --- | --- |
| SPE-5128 | There was a problem while retrieving siteUrls. Site URLs might be empty or null. | Provide at least one Site Url. | Site configuration error | Console: Site Configuration |
| SPE-5131 | There was a problem while retrieving username. Email was invalid. | Provide valid email address. | User email validation error | Console: User Configuration |
| SPE-5132 | There was a problem while retrieving url. This URL was invalid. | Provide a valid URL. | Provide a valid SharePoint site URL in the format https://your-sharepoint-site.com | Console: Site Configuration |
| SPE-5149 | The provided siteUrls contain duplicate sites. Remove duplicates. | Ensure SiteUrls must not be the same. | Duplicate site URL configuration error | Console: Site Configuration |
**Other Configuration issues**
| Error code | Error message | Suggested resolution | Context | Where to find error |
| --- | --- | --- | --- | --- |
| SPE-5133 | There was a problem while retrieving s3CertificateName. S3 Certificate Name might be empty or null. | When using certificate-based authentication, upload your authentication certificate to an S3 bucket and provide the certificate name and bucket details in the connector configuration. | S3 certificate configuration error | Console: Security Configuration |
| SPE-5134 | There was a problem while retrieving s3BucketName. S3 Bucket Name might be empty or null | When using certificate-based authentication, upload your authentication certificate to an S3 bucket and provide the certificate name and bucket details in the connector configuration. | S3 bucket configuration error | Console: S3 Configuration |
| SPE-5151 | Error parsing the field value. Size is over maximum allowed limit. | Reduce the field value size to within the maximum allowed limit. | Field size limit exceeded | Console: Field Configuration |
# Connecting SharePoint Server 2016 to Amazon Q Business
Microsoft SharePoint Server 2016
Microsoft SharePoint is a collaborative website building service that lets you customize web content and create web pages, web sites, document libraries, and lists. You can connect a SharePoint Server 2016 instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
Amazon Q supports Microsoft SharePoint Server (2016, 2019, and Subscription Edition).
**Topics**
+ [
# Known limitations for the Amazon Q Business SharePoint Server 2016 connector
](sharepoint-server-2016-limitations.md)
+ [
# SharePoint Server 2016 connector overview
](sharepoint-server-2016-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to SharePoint Server 2016
](sharepoint-server-2016-prereqs.md)
+ [
# Connecting Amazon Q Business to SharePoint Server 2016 using the console
](sharepoint-server-2016-console.md)
+ [
# Connecting Amazon Q Business to SharePoint Server 2016 using APIs
](sharepoint-server-2016-api.md)
+ [
# Connecting Amazon Q Business to SharePoint Server 2016 using AWS CloudFormation
](sharepoint-server-2016-cfn.md)
+ [
# How Amazon Q Business connector crawls SharePoint Server 2016 ACLs
](sharepoint-server-2016-user-management.md)
+ [
# Amazon Q Business SharePoint Server 2016 data source connector field mappings
](sharepoint-server-2016-field-mappings.md)
+ [
# IAM role for Amazon Q Business SharePoint Server 2016 connector
](sharepoint-server-2016-iam-role.md)
+ [
# Understand error codes in the SharePoint Server 2016 connector
](sharepoint-server-2016-error-codes.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Amazon Q Business SharePoint Server 2016 connector
Known limitations
The SharePoint Server 2016 connector has the following known limitations:
+ The SharePoint Server connector supports custom field mappings only for the **Files** entity.
+ For all SharePoint Server versions, the ACL token must be in lower case. For **Email with Domain from IDP** and **Email ID with Custom Domain** ACL, for example: *user@sharepoint2019.com*. For **Domain\$1User with Domain** ACL, for example: *sharepoint2013\$1user*.
+ If an entity name has a `%` character in its name, the connector will skip these files due to API limitations.
+ OneNote can only be crawled by the connector using a Tenant ID, and with OAuth 2.0, OAuth 2.0 refresh token, or SharePoint App Only authentication activated for SharePoint Online.
+ The connector crawls the first section of a OneNote document using its default name only, even if the document is renamed.
+ The connector crawls links in SharePoint 2016 if **Links** is selected as an entity to be crawled.
+ The connector crawls only list attachments and comments when **List Data** is selected as an entity to be crawled.
+ The connector crawls event attachments only when **Events** is also selected as an entity to be crawled.
+ To crawl nested groups using **Identity crawler**, you have to activate Local as well as AD Group Crawling.
+ To use **Identity Crawler** with SharePoint Server 2016 to crawl nested groups, you have to enable both Local and AD Group Crawling.
+ Query responses based on AD Group ACLs are not supported for SharePoint Server 2016. You need to add users and groups directly to your document permissions list.
+ When Access Control Lists (ACLs) are enabled, the "Sync only new or modified content" option is not available due to SharePoint Server 2016 API limitations. We recommend using "Full sync" or "New, modified, or deleted content sync" modes instead, or disable ACLs if you need to use this sync mode.
# SharePoint Server 2016 connector overview
Overview
The following table gives an overview of the Amazon Q Business SharePoint Server 2016 connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-overview.html)
# Prerequisites for connecting Amazon Q Business to SharePoint Server 2016
Prerequisites
The following page outlines the prerequisites you need to complete before connecting SharePoint Server 2016 to Amazon Q, based on the authentication mode of your choice.
**Topics**
+ [
## Prerequisites for using NTLM authentication
](#sharepoint-server-2016-prereqs-ntlm)
+ [
## Prerequisites for using Kerberos authentication
](#sharepoint-server-2016-prereqs-kerberos)
+ [
## Prerequisites for using SharePoint App-Only authentication
](#sharepoint-server-2016-prereqs-app-only)
## Prerequisites for using NTLM authentication
**If you're using NTLM authentication, make sure you've completed the following steps in SharePoint:**
+ Copied your SharePoint instance URLs. The format for the host URL you enter is *https://yourdomain.sharepoint.com/sites/mysite*. Your URL must start with `https` and contain `sharepoint.com`.
+ Copied the domain name of your SharePoint instance URL.
+ Generated an SSL certificate and uploaded it to an Amazon S3 bucket.
+ Noted the username and password that you use to connect to SharePoint.
**(Optional) If you're using **Email ID with Domain from IDP** to control access to your documents, make sure you've completed the following steps:**
+ Copied your LDAP Server Endpoint (endpoint of LDAP server including protocol and port number). For example: *ldap://example.com:389*.
+ Copied your LDAP Search Base (search base of the LDAP user). For example: *CN=Users,DC=sharepoint,DC=com*.
+ Copied your LDAP username and LDAP password.
**(Optional) If using **Email ID with Custom Domain** for access control, complete the following step:**
+ Noted your custom email domain value—for example: *"amazon.com"*.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your SharePoint Server 2016 authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
## Prerequisites for using Kerberos authentication
**If you're using Kerberos authentication, make sure you've completed the following steps in SharePoint:**
+ Copied your SharePoint instance URLs. The format for the host URL you enter is *https://yourdomain.sharepoint.com/sites/mysite*. Your URL must start with `https` and contain `sharepoint.com`.
+ Copied the domain name of your SharePoint instance URL.
+ Generated an SSL certificate and uploaded it to an Amazon S3 bucket.
+ Noted the username and password that you use to connect to SharePoint.
**(Optional) If you're using **Email ID with Domain from IDP** to control access to your documents, make sure you've completed the following steps:**
+ Copied your LDAP Server Endpoint (endpoint of LDAP server including protocol and port number). For example: *ldap://example.com:389*.
+ Copied your LDAP Search Base (search base of the LDAP user). For example: *CN=Users,DC=sharepoint,DC=com*.
+ Copied your LDAP username and LDAP password.
**(Optional) If using **Email ID with Custom Domain** for access control, complete the following step:**
+ Noted your custom email domain value—for example: *"amazon.com"*.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your SharePoint Server 2016 authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
## Prerequisites for using SharePoint App-Only authentication
**If you're using SharePoint App-Only authentication, make sure you've completed the following steps in SharePoint:**
+ Copied the SharePoint client ID generated when you registered App Only at Site Level. ClientID format is ClientID@TenantId. For example, *ffa956f3-8f89-44e7-b0e4-49670756342c@888d0b57-69f1-4fb8-957f-e1f0bedf82fe*.
+ Copied the SharePoint client secret generated when you registered App Only at Site Level.
**Important**
**Note: **Because client IDs and client secrets are generated for single sites only when you register SharePoint Server for App Only authentication, only one site URL is supported for SharePoint App Only authentication.
+ Noted the Tenant ID of your SharePoint account.
+ Noted your **LDAP Server Endpoint**, **LDAP Search Base**, **LDAP username**, and **LDAP password**.
**Note**
SharePoint App-Only Authentication is *not* supported for SharePoint 2013 version.
**(Optional) If you're using **Email ID with Domain from IDP** to control access to your documents, make sure you've completed the following steps:**
+ Copied your LDAP Server Endpoint (endpoint of LDAP server including protocol and port number). For example: *ldap://example.com:389*.
+ Copied your LDAP Search Base (search base of the LDAP user). For example: *CN=Users,DC=sharepoint,DC=com*.
+ Copied your LDAP username and LDAP password.
**(Optional) If using **Email ID with Custom Domain** for access control, complete the following step:**
+ Noted your custom email domain value—for example: *"amazon.com"*.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your SharePoint Server 2016 authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to SharePoint Server 2016 using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to SharePoint Server 2016 using the AWS Management Console.
**Connecting Amazon Q to SharePoint Server 2016**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **SharePoint** data source to your Amazon Q application.
1. Then, on the **SharePoint Server 2016** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
1. In **Source**, for **Hosting Method** – Choose **SharePoint Server**.
1. **Choose SharePoint Version** – Choose **SharePoint 2016**.
1. **Site URLs specific to your SharePoint repository** – Enter the SharePoint host URLs. The format for the host URLs you enter is *https://yourcompany/sites/mysite*. The URL must start with `https` protocol. Separate URLs with a new line. You can add up to 100 URLs.
1. **Domain** – Enter the SharePoint domain.
1. **SSL certificate location** – Enter the Amazon S3 path to your SSL certificate file.
1. For **Web proxy – *optional*** – Enter the host name (without the `http://` or `https://` protocol), and the port number used by the host URL transport protocol. The numeric value of the port number must be between 0 and 65535.
1. For **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. You can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details.See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. For SharePoint Server, you can choose from the following ACL options:
1. **Email ID with Domain from IDP** – Access control is based on email IDs that are extracted from email domains fetched from the underlying identity provider (IdP). You provide the IdP connection details in your Secrets Manager secret during **Authentication**.
1. **Email ID with Custom Domain** – Access control is based on email IDs. Provide the email domain value. For example, *"amazon.com"*. The email domain is used to construct the email ID for access control. You must enter your email domain using **Add Email Domain**.
See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. For **Authentication**, choose between **SharePoint App-Only authentication**, **NTLM authentication**, and **Kerberos authentication**, based on your use case.
1. Enter the following information for both **NTLM authentication** and **Kerberos authentication**:
For **AWS Secrets Manager secret** – Choose an existing secret or create a Secrets Manager secret to store your SharePoint authentication credentials. If you choose to create a secret, an AWS Secrets Manager secret window opens. Enter the following information in the window:
+ **Secret name** – A name for your secret.
+ **Username** – Username for your SharePoint account.
+ **Password** – Password for your SharePoint account.
If using **Email ID with Domain from IDP**, also enter your:
+ **LDAP Server Endpoint** – Endpoint of LDAP server, including protocol and port number. For example: *ldap://example.com:389*.
+ **LDAP Search Base** – Search base of LDAP user. For example: *CN=Users,DC=sharepoint,DC=com*.
+ **LDAP username** – Your LDAP username.
+ **LDAP Password** – Your LDAP password.
1. Enter the following information for **SharePoint App-Only authentication**:
For **AWS Secrets Manager secret** – Choose an existing secret or create a Secrets Manager secret to store your SharePoint authentication credentials. If you choose to create a secret, an AWS Secrets Manager secret window opens. Enter the following information in the window:
+ **Secret name** – A name for your secret.
+ **Client ID** – The SharePoint client ID that you generated when you registered App Only at Site Level. The ClientID format is ClientID@TenantId. For example, *ffa956f3-8f89-44e7-b0e4-49670756342c@888d0b57-69f1-4fb8-957f-e1f0bedf82fe*.
+ **SharePoint client secret** – The SharePoint client secret generated when your register for App Only at Site Level.
**Note:** Because client IDs and client secrets are generated for single sites only when you register SharePoint Server for App Only authentication, only one site URL is supported for SharePoint App Only authentication.
If using **Email ID with Domain from IDP**, also enter your:
+ **LDAP Server Endpoint** – Endpoint of LDAP server, including protocol and port number. For example: *ldap://example.com:389*.
+ **LDAP Search Base** – Search base of LDAP user. For example: *CN=Users,DC=sharepoint,DC=com*.
+ **LDAP username** – Your LDAP user name.
+ **LDAP Password** – Your LDAP password.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **Identity crawler** – Amazon Q crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. Only **Local Group Members** will be crawled by **Identity crawler**. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-connector.html#sharepoint-server-2016-iam).
1. In **Sync scope**, choose from the following options :
1. **Select entities** – Choose the entities that you want to crawl. You can select to crawl **All** entities or any combination of **Files**, **Attachments**, **Links**, **Pages**, **Events** and **List Data**.
1. In **Additional configuration – *optional***, for **Entity regex patterns** – Add regular expression patterns for **Links**, **Pages**, and **Events** to include specific entities instead of syncing all your documents.
1. **Regex patterns** – Add regular expression patterns to include or exclude files by **File path**, **File name**, **File type**, **OneNote section name**, and **OneNote page name** instead of syncing all your documents. You can add up to 100 patterns.
**Note**
Any valid regex pattern is supported. For example, if you use the regex `^QBusiness*`, any content starting with the word `QBusiness` followed by any number of characters will be filtered (`QBusiness_doc1` or `QBusiness`, but not `doc1_QBusiness`).
1. **Multi-media content configuration – optional** – To enable content extraction from embedded images and visuals in documents, choose **Visual content in documents**.
To extract audio transcriptions and video content, enable processing for the following file types:
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to SharePoint Server 2016 using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
**Topics**
+ [
## SharePoint Server 2016 configuration properties
](#sharepoint-server-2016-configuration-keys)
+ [
## SharePoint Server 2016 JSON schema
](#sharepoint-server-2016-json)
+ [
## SharePoint Server 2016 JSON schema example
](#sharepoint-server-2016-api-json-example)
## SharePoint Server 2016 configuration properties
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has a sub-property called `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-api.html) | Yes |
| `tenantId` | The tenant id of your SharePoint account. | `string` OAuth2 series required | Yes |
| `domain` | The domain of your SharePoint account. | `string` | Yes |
| `siteUrls` | The host URLs of your SharePoint account. | `array (string)` Specify the URL in the pattern `https://*` | Yes |
| `repositoryAdditionalProperties` | Additional properties to connect with your repository endpoint. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-api.html) | Yes |
| `authType` | The type of authentication you are using: NTLM, Kerberos, or OAuth2App. | `string` | Yes |
| `version` | The SharePoint version you are using: Sever. | `string (Server)` | Yes |
| `onPremVersion` | The SharePoint version that you are using. | `string` Valid values are ` ` (empty), `2013`, `2016`, `2019`, and `SubscriptionEdition`. | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-api.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-api.html) | A list of objects that map the attributes or field names of your SharePoint Server 2016 pages and assets to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-api.html) | No |
| `indexFieldName` | The field name of your SharePoint Server 2016 events, pages, files, links, attachments, or comments. | `string` | Yes |
| `indexFieldType` | The field type of your SharePoint Server 2016 events, pages, files, links, attachments, or comments. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your SharePoint Server 2016 events, pages, files, links, attachments, or comments. | `string` | Yes |
| `dateFieldFormat` | The date format of your SharePoint Server 2016 events, pages, files, links, attachments, or comments. | `string` Specify the date format in the form `yyyy-MM-dd"T"HH:mm:ss"Z"` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-api.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-api.html) | A list of regular expression patterns to include/exclude specific files in your SharePoint data source. Files that match the patterns are included in the index. File that don&t match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn&t included in the index. | `array (string)` | No |
| `aclConfiguration` | Specifes how your ACL is configured. | `string>` Valid values are `ACLWithLDAPEmailFmt`, `ACLWithManualEmailFmt`, or `ACLWithUsernameFmt`. | No |
| `proxyHost` | The host where the web proxy is required. The host name should be without protocol (http:// or https://). | `string` | Yes |
| `proxyPort` | Port used by the host URL transport protocol. The port number should be a numeric value between 0 and 65535. | `string` | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-api.html) | Input TRUE to index. | `boolean` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| `sslCertificatePath` | Configuration information to access the SSL certificate stored in your Amazon S3 bucket. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-api.html) | No |
| `bucket` | The name of the Amazon S3 bucket that stores your Microsoft Entra ID (formerly Azure AD) self-signed X.509 certificate. | `string` | Yes |
| `key` | The name of the SSL certificate stored in your Amazon S3 bucket. | `string` | Yes |
| `type` | We recommend that you use SHAREPOINTV2 as your data source type. | `string` Valid values are `SHAREPOINTV2` and `SHAREPOINT`. | Yes |
| `enableIdentityCrawler` | true to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. See [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler) for more information. | `boolean` | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-api.html) | Yes |
| `secretARN` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your SharePoint. If you use OAuth2App authentication, provide the client ID, client secret, LDAP URL, LDAP base DN, LDAP user name, and LDAP password. If you use NTLM or Kerberos authentication, provide the user name, password, LDAP URL, Base DN, LDAP user, and LDAP password. | `string` The minimum length is 20 and the maximum length is 2,048 characters. If you use Sharepoint App-Only authentication (`authType` should be `OAuth2App` authentication) the secret must contain a JSON structure with the following keys: {
"clientId": "client ID",
"clientSecret": "client secret",
"ldapUrl": "LDAP URL",
"ldbaseDn": "LDAP base DN",
"ldapUser": "LDAP user name",
"ldapPassword": "LDAP password"
} If you use NTLM authentication or Kerberos authentication, the secret must contain a JSON structure with the following keys: {
"userName": "SharePoint account user name",
"password": "SharePoint account password",
"ldapUrl": "LDAP URL",
"baseDn": "LDAP base DN",
"ldapUser": "LDAP user name",
"ldapPassword": "LDAP password"
} | Yes |
| `version` | The version of this template that&s currently supported. | `string` | No |
## SharePoint Server 2016 JSON schema
The following is the SharePoint Server 2016 JSON schema:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["SHAREPOINTV2", "SHAREPOINT"]
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"sslCertificatePath": {
"type": "object",
"properties": {
"bucket": {
"type": "string",
"pattern": "^[a-z0-9][\\.\\-a-z0-9]{1,61}[a-z0-9]$",
"minLength": 3,
"maxLength": 63
},
"key": {
"type": "string",
"minLength": 1,
"maxLength": 10240
}
},
"required": ["bucket", "key"]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"minLength": 36,
"maxLength": 36
},
"domain": {
"type": "string"
},
"siteUrls": {
"type": "array",
"items": {
"type": "string",
"pattern": "https://.*"
}
},
"repositoryAdditionalProperties": {
"type": "object",
"properties": {
"authType": {
"type": "string",
"enum": ["OAuth2App", "NTLM", "Kerberos"]
},
"version": {
"type": "string",
"enum": ["Server"]
},
"onPremVersion": {
"type": "string",
"enum": ["", "2013", "2016", "2019", "SubscriptionEdition"]
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": ["authType", "version"]
}
},
"required": ["siteUrls", "domain", "repositoryAdditionalProperties"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"event": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"page": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"file": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"link": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"eventTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"pageTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"linkTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"crawlFiles": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPages": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlEvents": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlComments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlLinks": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAttachments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlListData": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"aclConfiguration": {
"type": "string",
"enum": [
"ACLWithLDAPEmailFmt",
"ACLWithManualEmailFmt",
"ACLWithUsernameFmt"
]
},
"emailDomain": {
"type": "string"
},
"isCrawlLocalGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlAdGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"proxyHost": {
"type": "string"
},
"proxyPort": {
"type": "string"
},
"maxFileSizeInMegaBytes": {
"type": "string"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"type",
"secretArn",
"syncMode",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
## SharePoint Server 2016 JSON schema example
The following is the SharePoint Server 2016 JSON schema example:
```
{
"type": "SHAREPOINTV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-sharepoint-secret",
"enableIdentityCrawler": "true",
"sslCertificatePath": {
"bucket": "my-sharepoint-bucket",
"key": "ssl/cert.pem"
},
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"tenantId": "1234567a-890b-1234-567c-123456789012",
"domain": "mycompany.sharepoint.com",
"siteUrls": [
"https://mycompany.sharepoint.com/sites/TeamSite"
],
"repositoryAdditionalProperties": {
"authType": "OAuth2",
"version": "Server",
"onPremVersion": "2019",
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
},
"repositoryConfigurations": {
"event": {
"fieldMappings": [
{
"indexFieldName": "event_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"page": {
"fieldMappings": [
{
"indexFieldName": "page_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"file": {
"fieldMappings": [
{
"indexFieldName": "file_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"link": {
"fieldMappings": [
{
"indexFieldName": "link_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"eventTitleFilterRegEx": [
"^.*$"
],
"pageTitleFilterRegEx": [
"^.*$"
],
"linkTitleFilterRegEx": [
"^.*$"
],
"inclusionFilePath": [
"documents/"
],
"exclusionFilePath": [
"drafts/"
],
"inclusionFileTypePatterns": [
"*.pdf",
"*.docx"
],
"exclusionFileTypePatterns": [
"*.tmp"
],
"inclusionFileNamePatterns": [
"*report*"
],
"exclusionFileNamePatterns": [
"*draft*"
],
"inclusionOneNoteSectionNamePatterns": [
"*"
],
"exclusionOneNoteSectionNamePatterns": [
"archived"
],
"inclusionOneNotePageNamePatterns": [
"*"
],
"exclusionOneNotePageNamePatterns": [
"test"
],
"crawlFiles": "true",
"crawlPages": "true",
"crawlEvents": "true",
"crawlComments": "true",
"crawlLinks": "true",
"crawlAttachments": "true",
"crawlListData": "false",
"crawlAcl": "true",
"aclConfiguration": "ACLWithUsernameFmt",
"emailDomain": "mycompany.com",
"isCrawlLocalGroupMapping": "false",
"isCrawlAdGroupMapping": "true",
"proxyHost": "proxy.mycompany.com",
"proxyPort": "8080",
"maxFileSizeInMegaBytes": "50"
},
"version": "1.0.0"
}
```
# Connecting Amazon Q Business to SharePoint Server 2016 using AWS CloudFormation
Using the CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
**Topics**
+ [
## SharePoint Server 2016 configuration properties
](#sharepoint-server-2016-configuration-keys)
+ [
## SharePoint Server 2016 JSON schema for using the configuration property with AWS CloudFormation
](#sharepoint-server-2016-cfn-json)
+ [
## SharePoint Server 2016 YAML schema for using the configuration property with AWS CloudFormation
](#sharepoint-server-2016-cfn-yaml)
## SharePoint Server 2016 configuration properties
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has a sub-property called `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-cfn.html) | Yes |
| `tenantId` | The tenant id of your SharePoint account. | `string` OAuth2 series required | Yes |
| `domain` | The domain of your SharePoint account. | `string` | Yes |
| `siteUrls` | The host URLs of your SharePoint account. | `array (string)` Specify the URL in the pattern `https://*` | Yes |
| `repositoryAdditionalProperties` | Additional properties to connect with your repository endpoint. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-cfn.html) | Yes |
| `authType` | The type of authentication you are using: NTLM, Kerberos, or OAuth2App. | `string` | Yes |
| `version` | The SharePoint version you are using: Sever. | `string (Server)` | Yes |
| `onPremVersion` | The SharePoint version that you are using. | `string` Valid values are ` ` (empty), `2013`, `2016`, `2019`, and `SubscriptionEdition`. | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-cfn.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-cfn.html) | A list of objects that map the attributes or field names of your SharePoint Server 2016 pages and assets to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-cfn.html) | No |
| `indexFieldName` | The field name of your SharePoint Server 2016 events, pages, files, links, attachments, or comments. | `string` | Yes |
| `indexFieldType` | The field type of your SharePoint Server 2016 events, pages, files, links, attachments, or comments. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your SharePoint Server 2016 events, pages, files, links, attachments, or comments. | `string` | Yes |
| `dateFieldFormat` | The date format of your SharePoint Server 2016 events, pages, files, links, attachments, or comments. | `string` Specify the date format in the form `yyyy-MM-dd"T"HH:mm:ss"Z"` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-cfn.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-cfn.html) | A list of regular expression patterns to include/exclude specific files in your SharePoint data source. Files that match the patterns are included in the index. File that don&t match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn&t included in the index. | `array (string)` | No |
| `aclConfiguration` | Specifes how your ACL is configured. | `string>` Valid values are `ACLWithLDAPEmailFmt`, `ACLWithManualEmailFmt`, or `ACLWithUsernameFmt`. | No |
| `proxyHost` | The host where the web proxy is required. The host name should be without protocol (http:// or https://). | `string` | Yes |
| `proxyPort` | Port used by the host URL transport protocol. The port number should be a numeric value between 0 and 65535. | `string` | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-cfn.html) | Input TRUE to index. | `boolean` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| `sslCertificatePath` | Configuration information to access the SSL certificate stored in your Amazon S3 bucket. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-cfn.html) | No |
| `bucket` | The name of the Amazon S3 bucket that stores your Microsoft Entra ID (formerly Azure AD) self-signed X.509 certificate. | `string` | Yes |
| `key` | The name of the SSL certificate stored in your Amazon S3 bucket. | `string` | Yes |
| `type` | We recommend that you use SHAREPOINTV2 as your data source type. | `string` Valid values are `SHAREPOINTV2` and `SHAREPOINT`. | Yes |
| `enableIdentityCrawler` | true to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. See [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler) for more information. | `boolean` | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2016-cfn.html) | Yes |
| `secretARN` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your SharePoint. If you use OAuth2App authentication, provide the client ID, client secret, LDAP URL, LDAP base DN, LDAP user name, and LDAP password. If you use NTLM or Kerberos authentication, provide the user name, password, LDAP URL, Base DN, LDAP user, and LDAP password. | `string` The minimum length is 20 and the maximum length is 2,048 characters. If you use Sharepoint App-Only authentication (`authType` should be `OAuth2App` authentication) the secret must contain a JSON structure with the following keys: {
"clientId": "client ID",
"clientSecret": "client secret",
"ldapUrl": "LDAP URL",
"ldbaseDn": "LDAP base DN",
"ldapUser": "LDAP user name",
"ldapPassword": "LDAP password"
} If you use NTLM authentication or Kerberos authentication, the secret must contain a JSON structure with the following keys: {
"userName": "SharePoint account user name",
"password": "SharePoint account password",
"ldapUrl": "LDAP URL",
"baseDn": "LDAP base DN",
"ldapUser": "LDAP user name",
"ldapPassword": "LDAP password"
} | Yes |
| `version` | The version of this template that&s currently supported. | `string` | No |
## SharePoint Server 2016 JSON schema for using the configuration property with AWS CloudFormation
SharePoint Server 2016 JSON schema
The following is the SharePoint Server 2016 JSON schema and examples for the configuration property for AWS CloudFormation.
**Topics**
+ [
### SharePoint Server 2016 JSON schema for using the configuration property with AWS CloudFormation
](#sharepoint-server-2016-cfn-json-schema)
+ [
### SharePoint Server 2016 JSON schema example for using the configuration property with AWS CloudFormation
](#sharepoint-server-2016-cfn-json-example)
### SharePoint Server 2016 JSON schema for using the configuration property with AWS CloudFormation
SharePoint Server 2016 JSON schema
The following is the SharePoint Server 2016 JSON schema for the configuration property for CloudFormation
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["SHAREPOINTV2", "SHAREPOINT"]
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"sslCertificatePath": {
"type": "object",
"properties": {
"bucket": {
"type": "string",
"pattern": "^[a-z0-9][\\.\\-a-z0-9]{1,61}[a-z0-9]$",
"minLength": 3,
"maxLength": 63
},
"key": {
"type": "string",
"minLength": 1,
"maxLength": 10240
}
},
"required": ["bucket", "key"]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"minLength": 36,
"maxLength": 36
},
"domain": {
"type": "string"
},
"siteUrls": {
"type": "array",
"items": {
"type": "string",
"pattern": "https://.*"
}
},
"repositoryAdditionalProperties": {
"type": "object",
"properties": {
"authType": {
"type": "string",
"enum": ["OAuth2App", "NTLM", "Kerberos"]
},
"version": {
"type": "string",
"enum": ["Server"]
},
"onPremVersion": {
"type": "string",
"enum": ["", "2013", "2016", "2019", "SubscriptionEdition"]
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": ["authType", "version"]
}
},
"required": ["siteUrls", "domain", "repositoryAdditionalProperties"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"event": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"page": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"file": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"link": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"eventTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"pageTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"linkTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"crawlFiles": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPages": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlEvents": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlComments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlLinks": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAttachments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlListData": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"aclConfiguration": {
"type": "string",
"enum": [
"ACLWithLDAPEmailFmt",
"ACLWithManualEmailFmt",
"ACLWithUsernameFmt"
]
},
"emailDomain": {
"type": "string"
},
"isCrawlLocalGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlAdGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"proxyHost": {
"type": "string"
},
"proxyPort": {
"type": "string"
},
"maxFileSizeInMegaBytes": {
"type": "string"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"type",
"secretArn",
"syncMode",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
### SharePoint Server 2016 JSON schema example for using the configuration property with AWS CloudFormation
SharePoint Server 2016 JSON schema example
The following is the SharePoint Server 2016 JSON schema example for the configuration property for CloudFormation
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "CloudFormation SHAREPOINT Data Source Template",
"Resources": {
"DataSourceSharePoint": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": "app12345-1234-1234-1234-123456789012",
"IndexId": "indx1234-1234-1234-1234-123456789012",
"DisplayName": "MySharePointDataSource",
"RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role",
"Configuration": {
"type": "SHAREPOINTV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-sharepoint-secret",
"enableIdentityCrawler": "true",
"sslCertificatePath": {
"bucket": "my-sharepoint-bucket",
"key": "ssl/cert.pem"
},
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"tenantId": "1234567a-890b-1234-567c-123456789012",
"domain": "mycompany.sharepoint.com",
"siteUrls": [
"https://mycompany.sharepoint.com/sites/TeamSite"
],
"repositoryAdditionalProperties": {
"authType": "OAuth2",
"version": "Server",
"onPremVersion": "2019",
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
},
"repositoryConfigurations": {
"event": {
"fieldMappings": [
{
"indexFieldName": "event_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"page": {
"fieldMappings": [
{
"indexFieldName": "page_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"file": {
"fieldMappings": [
{
"indexFieldName": "file_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"link": {
"fieldMappings": [
{
"indexFieldName": "link_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"eventTitleFilterRegEx": [
"^.*$"
],
"pageTitleFilterRegEx": [
"^.*$"
],
"linkTitleFilterRegEx": [
"^.*$"
],
"inclusionFilePath": [
"documents/"
],
"exclusionFilePath": [
"drafts/"
],
"inclusionFileTypePatterns": [
"*.pdf",
"*.docx"
],
"exclusionFileTypePatterns": [
"*.tmp"
],
"inclusionFileNamePatterns": [
"*report*"
],
"exclusionFileNamePatterns": [
"*draft*"
],
"inclusionOneNoteSectionNamePatterns": [
"*"
],
"exclusionOneNoteSectionNamePatterns": [
"archived"
],
"inclusionOneNotePageNamePatterns": [
"*"
],
"exclusionOneNotePageNamePatterns": [
"test"
],
"crawlFiles": "true",
"crawlPages": "true",
"crawlEvents": "true",
"crawlComments": "true",
"crawlLinks": "true",
"crawlAttachments": "true",
"crawlListData": "false",
"crawlAcl": "true",
"aclConfiguration": "ACLWithUsernameFmt",
"emailDomain": "mycompany.com",
"isCrawlLocalGroupMapping": "false",
"isCrawlAdGroupMapping": "true",
"proxyHost": "proxy.mycompany.com",
"proxyPort": "8080",
"maxFileSizeInMegaBytes": "50"
}
}
}
}
}
}
```
## SharePoint Server 2016 YAML schema for using the configuration property with AWS CloudFormation
SharePoint Server 2016 YAML schema
The following is the SharePoint Server 2016 YAML schema and examples for the configuration property for AWS CloudFormation:
**Topics**
+ [
### SharePoint Server 2016 YAML schema for using the configuration property with AWS CloudFormation
](#sharepoint-server-2016-cfn-yaml-schema)
+ [
### SharePoint Server 2016 YAML schema example for using the configuration property with AWS CloudFormation
](#sharepoint-server-2016-cfn-yaml-example)
### SharePoint Server 2016 YAML schema for using the configuration property with AWS CloudFormation
SharePoint Server 2016 YAML schema
The following is the SharePoint Server 2016 YAML schema for the configuration property for CloudFormation.
```
type: object
properties:
type:
type: string
enum:
- SHAREPOINTV2
- SHAREPOINT
syncMode:
type: string
enum:
- FULL_CRAWL
- FORCED_FULL_CRAWL
- CHANGE_LOG
secretArn:
type: string
minLength: 20
maxLength: 2048
enableIdentityCrawler:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
sslCertificatePath:
type: object
properties:
bucket:
type: string
pattern: '^[a-z0-9][\\.\\-a-z0-9]{1,61}[a-z0-9]$'
minLength: 3
maxLength: 63
key:
type: string
minLength: 1
maxLength: 10240
required:
- bucket
- key
connectionConfiguration:
type: object
properties:
repositoryEndpointMetadata:
type: object
properties:
tenantId:
type: string
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
minLength: 36
maxLength: 36
domain:
type: string
siteUrls:
type: array
items:
type: string
pattern: "https://.*"
repositoryAdditionalProperties:
type: object
properties:
authType:
type: string
enum:
- OAuth2App
- NTLM
- Kerberos
version:
type: string
enum:
- Server
onPremVersion:
type: string
enum:
- ""
- "2013"
- "2016"
- "2019"
- SubscriptionEdition
enableDeletionProtection:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
default: false
deletionProtectionThreshold:
type: string
default: "15"
required:
- authType
- version
required:
- siteUrls
- domain
- repositoryAdditionalProperties
required:
- repositoryEndpointMetadata
repositoryConfigurations:
type: object
properties:
event:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
page:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
file:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
link:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
attachment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
comment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
required: []
additionalProperties:
type: object
properties:
eventTitleFilterRegEx:
type: array
items:
type: string
pageTitleFilterRegEx:
type: array
items:
type: string
linkTitleFilterRegEx:
type: array
items:
type: string
inclusionFilePath:
type: array
items:
type: string
exclusionFilePath:
type: array
items:
type: string
inclusionFileTypePatterns:
type: array
items:
type: string
exclusionFileTypePatterns:
type: array
items:
type: string
inclusionFileNamePatterns:
type: array
items:
type: string
exclusionFileNamePatterns:
type: array
items:
type: string
inclusionOneNoteSectionNamePatterns:
type: array
items:
type: string
exclusionOneNoteSectionNamePatterns:
type: array
items:
type: string
inclusionOneNotePageNamePatterns:
type: array
items:
type: string
exclusionOneNotePageNamePatterns:
type: array
items:
type: string
crawlFiles:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlPages:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlEvents:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlComments:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlLinks:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlAttachments:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlListData:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlAcl:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
aclConfiguration:
type: string
enum:
- ACLWithLDAPEmailFmt
- ACLWithManualEmailFmt
- ACLWithUsernameFmt
emailDomain:
type: string
isCrawlLocalGroupMapping:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
isCrawlAdGroupMapping:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
proxyHost:
type: string
proxyPort:
type: string
maxFileSizeInMegaBytes:
type: string
required: []
version:
type: string
anyOf:
- pattern: 1.0.0
required:
- type
- secretArn
- syncMode
- enableIdentityCrawler
- connectionConfiguration
- repositoryConfigurations
- additionalProperties
```
### SharePoint Server 2016 YAML schema example for using the configuration property with AWS CloudFormation
SharePoint Server 2016 JSON schema example
The following is the SharePoint Server 2016 YAML example for the Configuration property for CloudFormation:
```
{
"type": "SHAREPOINTV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-sharepoint-secret",
"enableIdentityCrawler": "true",
"sslCertificatePath": {
"bucket": "my-sharepoint-bucket",
"key": "ssl/cert.pem"
},
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"tenantId": "1234567a-890b-1234-567c-123456789012",
"domain": "mycompany.sharepoint.com",
"siteUrls": [
"https://mycompany.sharepoint.com/sites/TeamSite"
],
"repositoryAdditionalProperties": {
"authType": "OAuth2",
"version": "Server",
"onPremVersion": "2019",
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
},
"repositoryConfigurations": {
"event": {
"fieldMappings": [
{
"indexFieldName": "event_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"page": {
"fieldMappings": [
{
"indexFieldName": "page_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"file": {
"fieldMappings": [
{
"indexFieldName": "file_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"link": {
"fieldMappings": [
{
"indexFieldName": "link_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"eventTitleFilterRegEx": [
"^.*$"
],
"pageTitleFilterRegEx": [
"^.*$"
],
"linkTitleFilterRegEx": [
"^.*$"
],
"inclusionFilePath": [
"documents/"
],
"exclusionFilePath": [
"drafts/"
],
"inclusionFileTypePatterns": [
"*.pdf",
"*.docx"
],
"exclusionFileTypePatterns": [
"*.tmp"
],
"inclusionFileNamePatterns": [
"*report*"
],
"exclusionFileNamePatterns": [
"*draft*"
],
"inclusionOneNoteSectionNamePatterns": [
"*"
],
"exclusionOneNoteSectionNamePatterns": [
"archived"
],
"inclusionOneNotePageNamePatterns": [
"*"
],
"exclusionOneNotePageNamePatterns": [
"test"
],
"crawlFiles": "true",
"crawlPages": "true",
"crawlEvents": "true",
"crawlComments": "true",
"crawlLinks": "true",
"crawlAttachments": "true",
"crawlListData": "false",
"crawlAcl": "true",
"aclConfiguration": "ACLWithUsernameFmt",
"emailDomain": "mycompany.com",
"isCrawlLocalGroupMapping": "false",
"isCrawlAdGroupMapping": "true",
"proxyHost": "proxy.mycompany.com",
"proxyPort": "8080",
"maxFileSizeInMegaBytes": "50"
},
"version": "1.0.0"
}
```
# How Amazon Q Business connector crawls SharePoint Server 2016 ACLs
ACL crawling
When you connect an SharePoint Server 2016 data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your SharePoint Server 2016 instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
To filter using a username, use the **User principal name** from your Azure portal. For example, johnstiles@kendra.onmicrosoft.com.
When you use a SharePoint group for user context filtering, calculate the group ID as follows:
**For local groups**
1. Get the site name. For example, `https://host.onmicrosoft.com/sites/siteName.`
1. Take the SHA256 hash of the site name. For example, `430a6b90503eef95c89295c8999c7981`.
1. Create the group ID by concatenating the SHA256 hash with a vertical bar ( \$1 ) and the group name. For example, if the group name is "local group name", the group ID is the following:
`"430a6b90503eef95c89295c8999c7981 | localGroupName"` (with a space before and after the vertical bar).
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Amazon Q Business SharePoint Server 2016 data source connector field mappings
Field mappings
To help you structure data for retrieval and chat filtering, Amazon Q Business crawls data source document attributes or metadata and maps them to fields in your Amazon Q index.
Amazon Q has reserved fields that it uses when querying your application. When possible, Amazon Q automatically maps these built-in fields to attributes in your data source. If a built-in field doesn't have a default mapping, or if you want to map additional index fields, use the custom field mappings to specify how a data source attribute maps to your Amazon Q application. You create field mappings by editing your data source after your application environment and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes-types.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Sharepoint connector supports the following entities and the associated reserved and custom attributes.
**Important**
If you map any SharePoint Server 2016 field to Amazon Q document title and document body fields, Amazon Q will generate responses from data in the document title and body.
**Note**
You can map any Sharepoint field to the document title or document body Amazon Q reserved/default index fields.
**Topics**
+ [
## Files
](#sharepoint-field-mappings-files)
+ [
## Events
](#sharepoint-field-mappings-events)
+ [
## Pages
](#sharepoint-field-mappings-pages)
+ [
## Links
](#sharepoint-field-mappings-links)
+ [
## Attachments
](#sharepoint-field-mappings-attachments)
+ [
## Comments
](#sharepoint-field-mappings-comments)
## Files
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | sp\$1title | Custom | String |
| sourceUri | \$1source\$1uri | Default | String |
| checkInComment | sp\$1checkInComment | Custom | String |
| size | sp\$1sizeLong | Custom | Long (numeric) |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| createdAt | \$1created\$1at | Default | Date |
| author | \$1authors | Default | String list |
| majorVersion | sp\$1majorVersion | Custom | String |
| uiVersionLabel | sp\$1uiVersionLabel | Custom | String |
| uniqueId | sp\$1uniqueId | Custom | String |
| irmEnabled | sp\$1irmEnabled | Custom | String |
| checkOutType | sp\$1checkOutType | Custom | String |
| category | \$1category | Default | String |
| modifiedBy | sp\$1modifiedBy | Custom | String |
| level | sp\$1level | Custom | String |
| uiVersion | sp\$1uiVersion | Custom | String |
| contentTag | sp\$1contentTag | Custom | String |
| eTag | sp\$1eTag | Custom | String |
| oneNoteDocument | sp\$1oneNoteDocument | Custom | String |
| oneNoteSection | sp\$1oneNoteSection | Custom | String |
| oneNotePage | sp\$1oneNotePage | Custom | String |
## Events
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | sp\$1title | Custom | String |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| sourceUri | \$1source\$1uri | Default | String |
| attachments | sp\$1hasAttachments | Custom | String |
| createdDate | \$1created\$1at | Default | Date |
| authorId | sp\$1authorId | Custom | String |
| editorId | sp\$1editorId | Custom | String |
| location | sp\$1location | Custom | String |
| eventDate | sp\$1eventDate | Custom | Date |
| eventEndDate | sp\$1eventEndDate | Custom | Date |
| ifRecurrence | sp\$1ifRecurrence | Custom | String |
| ifAllDayEvent | sp\$1ifAllDayEvent | Custom | String |
| category | \$1category | Default | String |
| eventCategory | sp\$1eventcategory | Custom | String |
## Pages
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| createdDateTime | \$1created\$1at | Default | Date |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| title | sp\$1title | Custom | String |
| sourceUri | \$1source\$1uri | Default | String |
| firstPublishedDate | sp\$1firstPublishedDate | Custom | Date |
| authorId | sp\$1authorId | Custom | String |
| editorId | sp\$1editorId | Custom | String |
| category | \$1category | Default | String |
## Links
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| createdAt | \$1created\$1at | Default | Date |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| title | sp\$1title | Custom | String |
| sourceUri | \$1source\$1uri | Default | String |
| fileType | sp\$1fileType | Custom | String |
| fileDirPath | sp\$1fileDirPath | Custom | String |
| firstPublishedDate | sp\$1firstPublishedDate | Custom | Date |
| authorId | sp\$1authorId | Custom | String |
| editorId | sp\$1editorId | Custom | String |
| category | \$1category | Default | String |
| size | sp\$1sizeLong | Custom | Long (numeric) |
## Attachments
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | sp\$1\$1title | Custom | String |
| parentCreatedDate | \$1created\$1at | Default | Date |
| sourceUri | \$1source\$1uri | Default | String |
| parentModifiedDate | \$1last\$1updated\$1at | Custom | Date |
| parentListId | sp\$1parentListId | Custom | String |
| parentTitle | sp\$1parentTitle | Custom | String |
| category | \$1category | Default | String |
## Comments
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| createdDateTime | \$1created\$1at | Default | Date |
| likedBy | sp\$1likedBy | Custom | String |
| sourceUri | \$1source\$1uri | Custom | String |
| isReply | sp\$1isReply | Custom | String |
| author | \$1authors | Default | String list |
| listId | sp\$1listId | Custom | String |
| category | \$1category | Default | String |
| replyCount | sp\$1replyCount | Custom | String |
| parentTitle | sp\$1parentTitle | Custom | String |
# IAM role for Amazon Q Business SharePoint Server 2016 connector
IAM role
**Note**
**(Optional)** If you use **Azure App-Only authentication**, you also need to add permissions for Amazon Q to access the certificate stored in your Amazon S3 bucket.
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Understand error codes in the SharePoint Server 2016 connector
Error Codes
The following table provides information about error codes you may see for the Microsoft SharePoint connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| SPE-5001 | Authentication failed. Configuration might contain wrong credentials. | Provide valid credentials like username, password or client Id, client secret and tenant Id. |
| SPE-5002 | There was a problem while connecting to Host Url and/or Domain. hostUrl and/or domain values might be incorrect. | Provide valid Host URL or Domain. |
| SPE-5003 | Provided URL is incorrect | Provide correct URL. |
| SPE-5004 | Inet Address validation Failed. | Provide valid Inet Address |
| SPE-5005 | Failed : HTTP protocol violation has occurred. | Try running the connector again. |
| SPE-5006 | Cannot connect to proxy. Check the proxy configurations. | Provide valid Proxy configuration details. |
| SPE-5007 | Proxy port is invalid. Check the proxy port. | Provide valid Proxy port. |
| SPE-5008 | Valid SSL Certificate could not be found for connector. | Provide valid SSL certificate. |
| SPE-5009 | There was a problem while connecting to LDAP. Check LDAP configuration. | Provide valid LDAP configuration details. |
| SPE-5100 | There was a problem while retrieving repositoryId. Repository ID might be empty or null. | Ensure that repository Id must not be null or empty. |
| SPE-5101 | There was a problem while retrieving dataSourceIamRoleArn. Data Source IAM Role ARN might be empty or null. | Ensure that dataSourceIamRoleArn must not be null or empty. |
| SPE-5102 | There was a problem while retrieving repository configurations. Repository configurations might be empty or incorrect. | Provide valid repository configurations. |
| SPE-5115 | There was a problem while retrieving field mapping values for event entity. Field mapping values might be empty or incorrect. | Field mapping values for event entity should be correct or non-empty. |
| SPE-5116 | There was a problem while retrieving field mapping values for file entity. Field mapping values might be empty or incorrect. | Field mapping values for file entity should be correct or non-empty. |
| SPE-5117 | There was a problem while retrieving field mapping values for page entity. Field mapping values might be empty or incorrect. | Field mapping values for page entity should be correct or non-empty. |
| SPE-5118 | There was a problem while retrieving field mapping values for link entity. Field mapping values might be empty or incorrect. | Field mapping values for link entity should be correct or non-empty. |
| SPE-5119 | There was a problem while retrieving field mapping values for comment entity. Field mapping values might be empty or incorrect. | Field mapping values for comment entity should be correct or non-empty. |
| SPE-5120 | There was a problem while retrieving field mapping values for attachment entity. Field mapping values might be empty or incorrect. | Field mapping values for attachment entity should be correct or non-empty. |
| SPE-5121 | There was a problem while retrieving values for crawl entities. Values might be empty or incorrect. It should be either true or false. | There might be some incorrect value given in any one of the crawling entities like – null, TRUE or any dummy string. Ensure the value must be non-empty and either true or false. |
| SPE-5122 | There was a problem while retrieving domain. Domain might be empty or null. | Provide Client Id. |
| SPE-5123 | There was a problem while retrieving version. Version might be empty or null. | Provide valid version and it should not be null. |
| SPE-5124 | There was a problem while retrieving authType. Auth-Type might be empty or null. | Ensure AUTH Type in configuration must be not null. |
| SPE-5125 | There was a problem while retrieving clientId. Client ID might be empty or null. | Provide Client Id. |
| SPE-5126 | There was a problem while retrieving clientSecret. Client Secret might be empty or null. | Provide Client Secret. |
| SPE-5127 | There was a problem while retrieving tenantId. Tenant ID might be empty or null. | Provide Tenant Id. |
| SPE-5128 | There was a problem while retrieving siteUrls. Site URLs might be empty or null. | Provide at least one Site Url. |
| SPE-5129 | There was a problem while retrieving password. Password might be empty or null. | Provide password. |
| SPE-5130 | There was a problem while retrieving username.Username might be empty or null. | Provide username. |
| SPE-5131 | There was a problem while retrieving username. Email was invalid. | Provide valid email address. |
| SPE-5132 | There was a problem while retrieving url. This URL was invalid. | Provide a valid URL. |
| SPE-5133 | There was a problem while retrieving s3CertificateName. S3 Certificate Name might be empty or null. | Ensure s3CertificateName is not null or non-empty. |
| SPE-5134 | There was a problem while retrieving s3BucketName. S3 Bucket Name might be empty or null | Ensure s3BucketName is not null or non-empty. |
| SPE-5135 | The provided version was not a valid Sharepoint Connector version. Version should be one of [Online, Server]. | Version should be one of [Online, Server]. |
| SPE-5136 | The provided authType was not a valid Sharepoint Connector authentication method. | Provide valid authType. The value of authType should be one of [Basic, OAuth2Certificate, OAuth2]. |
| SPE-5138 | There was a problem while retrieving onPremVersion. On prem Version might be empty or null | Ensure onPremVersion is not be null or non-empty. |
| SPE-5139 | The provided onPremVersion was not valid Sharepoint on-prem version. On prem version should be one of [2013, 2016, 2019, SubscriptionEdition]. | Provide a valid onPremVersion. On prem version should be one of [2013, 2016, 2019, SubscriptionEdition]. |
| SPE-5140 | There was a problem while retrieving ldapUrl. LDAP Url might be empty or null. | Ensure ldapUrl is not null or empty. |
| SPE-5141 | There was a problem while retrieving baseDn. Base DN might be empty or null. | Ensure baseDn is not be null or empty. |
| SPE-5142 | There was a problem while retrieving privateKey. Private Key might be empty or null. | Please ensure privateKey is not be null or empty. |
| SPE-5144 | There was a problem while retrieving aclConfiguration. ACL Configuration might be empty, null or invalid | Provide valid aclConfiguration. aclConfiguration should be one of [ ACLWithLDAPEmailFmt, ACLWithManualEmailFmt, ACLWithUsernameFmt ]. |
| SPE-5145 | There was a problem while retrieving emailDomain. Email Domain might be empty or null. | Ensure emailDomain is not null or empty. |
| SPE-5146 | There was a problem while retrieving ldapUsername. LDAP Username might be empty or null. | Ensure ldapUser is not null or empty. |
| SPE-5147 | There was a problem while retrieving ldapPassword. LDAP Password might be empty or null. | Ensure ldapPassword is not null or empty. |
| SPE-5149 | The provided siteUrls contain duplicate sites. Remove duplicates. | Ensure SiteUrls must not be the same. |
| SPE-5150 | Invalid Client Id pattern. | Provide the correct client ID. |
| SPE-5151 | Error parsing the field value. Size is over maximum allowed limit. | Ensure the size limit. |
| SPE-5152 | There was a problem while retrieving AD Client ID. AD Client ID should not be empty. | Ensure AD Client Id must be non-empty. |
| SPE-5153 | Invalid AD Client Id pattern. | Provide valid AD Client Id pattern. |
| SPE-5154 | There was a problem while retrieving AD Client Secret. AD Client Secret should not be empty. | Ensure AD Client Secret is non-empty. |
| SPE-5155 | There can't be more than one site for SharePoint on-prem app-only authentication. | Ensure that their must be only single site present for SharePoint on-prem app-only authentication. |
| SPE-5200 | There was a problem while connecting to the URL. | Ensure the siteUrl exists. |
# Connecting SharePoint Server 2019 to Amazon Q Business
Microsoft SharePoint Server 2019
Microsoft SharePoint is a collaborative website building service that lets you customize web content and create web pages, web sites, document libraries, and lists. You can connect a SharePoint Server 2019 instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
Amazon Q supports Microsoft SharePoint Server (versions 2016, 2019, and Subscription Edition).
**Topics**
+ [
# Known limitations for the Amazon Q Business SharePoint Server 2019 connector
](sharepoint-server-2019-limitations.md)
+ [
# SharePoint Server 2019 connector overview
](sharepoint-server-2019-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to SharePoint Server 2019
](sharepoint-server-2019-prereqs.md)
+ [
# Connecting Amazon Q Business to SharePoint Server 2019 using the console
](sharepoint-server-2019-console.md)
+ [
# Connecting Amazon Q Business to SharePoint Server 2019 using APIs
](sharepoint-server-2019-api.md)
+ [
# Connecting Amazon Q Business to SharePoint Server 2019 using AWS CloudFormation
](sharepoint-server-2019-cfn.md)
+ [
# How Amazon Q Business connector crawls SharePoint Server 2019 ACLs
](sharepoint-server-2019-user-management.md)
+ [
# Amazon Q Business SharePoint Server 2019 data source connector field mappings
](sharepoint-server-2019-field-mappings.md)
+ [
# IAM role for Amazon Q Business SharePoint Server 2019 connector
](sharepoint-server-2019-iam-role.md)
+ [
# Understand error codes in the SharePoint Server 2019 connector
](sharepoint-server-2019-error-codes.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Amazon Q Business SharePoint Server 2019 connector
Known limitations
The SharePoint Server 2019 connector has the following known limitations:
+ The Amazon Q SharePoint connector supports custom field mappings only for the **Files** entity.
+ For all SharePoint Server versions, the ACL token must be in lower case. For **Email with Domain from IDP** and **Email ID with Custom Domain** ACL, for example: *user@sharepoint2019.com*. For **Domain\$1User with Domain** ACL, for example: *sharepoint2013\$1user*.
+ If an entity name has a `%` character in its name, the connector will skip these files due to API limitations.
+ OneNote can only be crawled by the connector using a Tenant ID, and with OAuth 2.0, OAuth 2.0 refresh token, or SharePoint App Only authentication activated for SharePoint Online.
+ The connector crawls the first section of a OneNote document using its default name only, even if the document is renamed.
+ The connector crawls links in SharePoint 2019 only if **Pages** and **Files** are selected as entities to be crawled in addition to **Links**.
+ The connector crawls only list attachments and comments when **List Data** is selected as an entity to be crawled.
+ The connector crawls event attachments only when **Events** is also selected as an entity to be crawled.
+ To crawl nested groups using **Identity crawler**, you have to activate Local as well as AD Group Crawling.
+ To use **Identity Crawler** with SharePoint Server 2019 to crawl nested groups, you have to enable both Local and AD Group Crawling.
+ Query responses based on AD Group ACLs are not supported for SharePoint Server 2019. You need to add users and groups directly to your document permissions list.
+ When Access Control Lists (ACLs) are enabled, the "Sync only new or modified content" option is not available due to SharePoint Server 2019 API limitations. We recommend using "Full sync" or "New, modified, or deleted content sync" modes instead, or disable ACLs if you need to use this sync mode.
# SharePoint Server 2019 connector overview
Overview
The following table gives an overview of the Amazon Q Business SharePoint Server 2019 connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-overview.html)
# Prerequisites for connecting Amazon Q Business to SharePoint Server 2019
Prerequisites
The following page outlines the prerequisites you need to complete before connecting SharePoint Server 2019 to Amazon Q, based on the authentication mode of your choice.
**Topics**
+ [
## Prerequisites for using NTLM authentication
](#sharepoint-server-2019-prereqs-ntlm)
+ [
## Prerequisites for using Kerberos authentication
](#sharepoint-server-2019-prereqs-kerberos)
+ [
## Prerequisites for using SharePoint App-Only authentication
](#sharepoint-server-2019-prereqs-app-only)
## Prerequisites for using NTLM authentication
**If you're using NTLM authentication, make sure you've completed the following steps in SharePoint Server 2019:**
+ Copied your SharePoint instance URLs. The format for the host URL you enter is *https://yourdomain.sharepoint.com/sites/mysite*. Your URL must start with `https` and contain `sharepoint.com`.
+ Copied the domain name of your SharePoint instance URL.
+ Generated an SSL certificate and uploaded it to an Amazon S3 bucket.
+ Noted the username and password that you use to connect to SharePoint.
**If you're using **Email ID with Domain from IDP** to control access to your documents, make sure you've completed the following steps:**
+ Copied your LDAP Server Endpoint (endpoint of LDAP server including protocol and port number). For example: *ldap://example.com:389*.
+ Copied your LDAP Search Base (search base of the LDAP user). For example: *CN=Users,DC=sharepoint,DC=com*.
+ Copied your LDAP username and LDAP password.
**If using **Email ID with Custom Domain** for access control, complete the following step:**
+ Noted your custom email domain value—for example: *"amazon.com"*.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your SharePoint Server 2019 authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
## Prerequisites for using Kerberos authentication
**If you're using Kerberos authentication, make sure you've completed the following steps in SharePoint Server 2019:**
+ Copied your SharePoint instance URLs. The format for the host URL you enter is *https://yourdomain.sharepoint.com/sites/mysite*. Your URL must start with `https` and contain `sharepoint.com`.
+ Copied the domain name of your SharePoint instance URL.
+ Generated an SSL certificate and uploaded it to an Amazon S3 bucket.
+ Noted the username and password that you use to connect to SharePoint.
**(Optional) If you're using **Email ID with Domain from IDP** to control access to your documents, make sure you've completed the following steps:**
+ Copied your LDAP Server Endpoint (endpoint of LDAP server including protocol and port number). For example: *ldap://example.com:389*.
+ Copied your LDAP Search Base (search base of the LDAP user). For example: *CN=Users,DC=sharepoint,DC=com*.
+ Copied your LDAP username and LDAP password.
**(Optional) If using **Email ID with Custom Domain** for access control, complete the following step:**
+ Noted your custom email domain value—for example: *"amazon.com"*.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your SharePoint Server 2019 authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
## Prerequisites for using SharePoint App-Only authentication
**If you're using SharePoint App-Only authentication, make sure you've completed the following steps in SharePoint Server 2019:**
+ Copied the SharePoint client ID generated when you registered App Only at Site Level. ClientID format is ClientID@TenantId. For example, *ffa956f3-8f89-44e7-b0e4-49670756342c@888d0b57-69f1-4fb8-957f-e1f0bedf82fe*.
+ Copied the SharePoint client secret generated when you registered App Only at Site Level.
**Important**
**Note: **Because client IDs and client secrets are generated for single sites only when you register SharePoint Server for App Only authentication, only one site URL is supported for SharePoint App Only authentication.
+ Noted the Tenant ID of your SharePoint account.
+ Noted your **LDAP Server Endpoint**, **LDAP Search Base**, **LDAP username**, and **LDAP password**.
**Note**
SharePoint App-Only Authentication is *not* supported for SharePoint 2013 version.
**(Optional) If you're using **Email ID with Domain from IDP** to control access to your documents, make sure you've completed the following steps:**
+ Copied your LDAP Server Endpoint (endpoint of LDAP server including protocol and port number). For example: *ldap://example.com:389*.
+ Copied your LDAP Search Base (search base of the LDAP user). For example: *CN=Users,DC=sharepoint,DC=com*.
+ Copied your LDAP username and LDAP password.
**(Optional) If using **Email ID with Custom Domain** for access control, complete the following step:**
+ Noted your custom email domain value—for example: *"amazon.com"*.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your SharePoint Server 2019 authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to SharePoint Server 2019 using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to SharePoint Server 2019 using the AWS Management Console.
**Connecting Amazon Q to SharePoint Server 2019**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **SharePoint** data source to your Amazon Q application.
1. Then, on the **SharePoint Server 2019** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
1. In **Source**, for **Hosting Method** – Choose **SharePoint Server**.
1. **Choose SharePoint Version** – Choose **SharePoint 2019**.
1. **Site URLs specific to your SharePoint repository** – Enter the SharePoint host URLs. The format for the host URLs you enter is *https://yourcompany/sites/mysite*. The URL must start with `https` protocol. Separate URLs with a new line. You can add up to 100 URLs.
1. **Domain** – Enter the SharePoint domain.
1. **SSL certificate location** – Enter the Amazon S3 path to your SSL certificate file.
1. For **Web proxy – *optional*** – Enter the host name (without the `http://` or `https://` protocol), and the port number used by the host URL transport protocol. The numeric value of the port number must be between 0 and 65535.
1. For **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. You can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. For SharePoint Server, you can choose from the following ACL options:
1. **Email ID with Domain from IDP** – Access control is based on email IDs that are extracted from email domains fetched from the underlying identity provider (IdP). You provide the IdP connection details in your Secrets Manager secret during **Authentication**.
1. **Email ID with Custom Domain** – Access control is based on email IDs. Provide the email domain value. For example, *"amazon.com"*. The email domain is used to construct the email ID for access control. You must enter your email domain using **Add Email Domain**.
See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. For **Authentication**, choose between **SharePoint App-Only authentication**, **NTLM authentication**, and **Kerberos authentication**, based on your use case.
1. Enter the following information for both **NTLM authentication** and **Kerberos authentication**:
For **AWS Secrets Manager secret** – Choose an existing secret or create a Secrets Manager secret to store your SharePoint authentication credentials. If you choose to create a secret, an AWS Secrets Manager secret window opens. Enter the following information in the window:
+ **Secret name** – A name for your secret.
+ **Username** – Username for your SharePoint account.
+ **Password** – Password for your SharePoint account.
If using **Email ID with Domain from IDP**, also enter your:
+ **LDAP Server Endpoint** – Endpoint of LDAP server, including protocol and port number. For example: *ldap://example.com:389*.
+ **LDAP Search Base** – Search base of LDAP user. For example: *CN=Users,DC=sharepoint,DC=com*.
+ **LDAP username** – Your LDAP username.
+ **LDAP Password** – Your LDAP password.
1. Enter the following information for **SharePoint App-Only authentication**:
For **AWS Secrets Manager secret** – Choose an existing secret or create a Secrets Manager secret to store your SharePoint authentication credentials. If you choose to create a secret, an AWS Secrets Manager secret window opens. Enter the following information in the window:
+ **Secret name** – A name for your secret.
+ **Client ID** – The SharePoint client ID that you generated when you registered App Only at Site Level. The ClientID format is ClientID@TenantId. For example, *ffa956f3-8f89-44e7-b0e4-49670756342c@888d0b57-69f1-4fb8-957f-e1f0bedf82fe*.
+ **SharePoint client secret** – The SharePoint client secret generated when your register for App Only at Site Level.
**Note:** Because client IDs and client secrets are generated for single sites only when you register SharePoint Server for App Only authentication, only one site URL is supported for SharePoint App Only authentication.
If using **Email ID with Domain from IDP**, also enter your:
+ **LDAP Server Endpoint** – Endpoint of LDAP server, including protocol and port number. For example: *ldap://example.com:389*.
+ **LDAP Search Base** – Search base of LDAP user. For example: *CN=Users,DC=sharepoint,DC=com*.
+ **LDAP username** – Your LDAP user name.
+ **LDAP Password** – Your LDAP password.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **Identity crawler** – Amazon Q crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. Only **Local Group Members** will be crawled by **Identity crawler**. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-connector.html#sharepoint-server-2019-iam).
1. In **Sync scope**, choose from the following options :
1. **Select entities** – Choose the entities that you want to crawl. You can select to crawl **All** entities or any combination of **Files**, **Attachments**, **Links**, **Pages**, **Events** and **List Data**.
1. In **Additional configuration – *optional***, for **Entity regex patterns** – Add regular expression patterns for **Links**, **Pages**, and **Events** to include specific entities instead of syncing all your documents.
1. **Regex patterns** – Add regular expression patterns to include or exclude files by **File path**, **File name**, **File type**, **OneNote section name**, and **OneNote page name** instead of syncing all your documents. You can add up to 100 patterns.
**Note**
Any valid regex pattern is supported. For example, if you use the regex `^QBusiness*`, any content starting with the word `QBusiness` followed by any number of characters will be filtered (`QBusiness_doc1` or `QBusiness`, but not `doc1_QBusiness`).
1. **Multi-media content configuration – optional** – To enable content extraction from embedded images and visuals in documents, choose **Visual content in documents**.
To extract audio transcriptions and video content, enable processing for the following file types:
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to SharePoint Server 2019 using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
**Topics**
+ [
## SharePoint Server 2019 configuration properties
](#sharepoint-server-2019-configuration-keys)
+ [
## SharePoint Server 2019 JSON schema
](#sharepoint-server-2019-json)
+ [
## SharePoint Server 2019 JSON schema example
](#sharepoint-server-2019-api-json-example)
## SharePoint Server 2019 configuration properties
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has a sub-property called `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-api.html) | Yes |
| `tenantId` | The tenant id of your SharePoint account. | `string` OAuth2 series required | Yes |
| `domain` | The domain of your SharePoint account. | `string` | Yes |
| `siteUrls` | The host URLs of your SharePoint account. | `array (string)` Specify the URL in the pattern `https://*` | Yes |
| `repositoryAdditionalProperties` | Additional properties to connect with your repository endpoint. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-api.html) | Yes |
| `authType` | The type of authentication you are using: NTLM, Kerberos, or OAuth2App. | `string` | Yes |
| `version` | The SharePoint version you are using: Sever. | `string (Server)` | Yes |
| `onPremVersion` | The SharePoint version that you are using. | `string` Valid values are ` ` (empty), `2013`, `2016`, `2019`, and `SubscriptionEdition`. | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-api.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-api.html) | A list of objects that map the attributes or field names of your SharePoint Server 2019 pages and assets to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-api.html) | No |
| `indexFieldName` | The field name of your SharePoint Server 2019 events, pages, files, links, attachments, or comments. | `string` | Yes |
| `indexFieldType` | The field type of your SharePoint Server 2019 events, pages, files, links, attachments, or comments. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your SharePoint Server 2019 events, pages, files, links, attachments, or comments. | `string` | Yes |
| `dateFieldFormat` | The date format of your SharePoint Server 2019 events, pages, files, links, attachments, or comments. | `string` Specify the date format in the form `yyyy-MM-dd"T"HH:mm:ss"Z"` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-api.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-api.html) | A list of regular expression patterns to include/exclude specific files in your SharePoint data source. Files that match the patterns are included in the index. File that don&t match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn&t included in the index. | `array (string)` | No |
| `aclConfiguration` | Specifes how your ACL is configured. | `string>` Valid values are `ACLWithLDAPEmailFmt`, `ACLWithManualEmailFmt`, or `ACLWithUsernameFmt`. | No |
| `proxyHost` | The host where the web proxy is required. The host name should be without protocol (http:// or https://). | `string` | Yes |
| `proxyPort` | Port used by the host URL transport protocol. The port number should be a numeric value between 0 and 65535. | `string` | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-api.html) | Input TRUE to index. | `boolean` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| `sslCertificatePath` | Configuration information to access the SSL certificate stored in your Amazon S3 bucket. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-api.html) | No |
| `bucket` | The name of the Amazon S3 bucket that stores your Microsoft Entra ID (formerly Azure AD) self-signed X.509 certificate. | `string` | Yes |
| `key` | The name of the SSL certificate stored in your Amazon S3 bucket. | `string` | Yes |
| `type` | We recommend that you use SHAREPOINTV2 as your data source type. | `string` Valid values are `SHAREPOINTV2` and `SHAREPOINT`. | Yes |
| `enableIdentityCrawler` | true to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. See [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler) for more information. | `boolean` | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-api.html) | Yes |
| `secretARN` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your SharePoint. If you use OAuth2App authentication, provide the client ID, client secret, LDAP URL, LDAP base DN, LDAP user name, and LDAP password. If you use NTLM or Kerberos authentication, provide the user name, password, LDAP URL, Base DN, LDAP user, and LDAP password. | `string` The minimum length is 20 and the maximum length is 2,048 characters. If you use Sharepoint App-Only authentication (`authType` should be `OAuth2App` authentication) the secret must contain a JSON structure with the following keys: {
"clientId": "client ID",
"clientSecret": "client secret",
"ldapUrl": "LDAP URL",
"ldbaseDn": "LDAP base DN",
"ldapUser": "LDAP user name",
"ldapPassword": "LDAP password"
} If you use NTLM authentication or Kerberos authentication, the secret must contain a JSON structure with the following keys: {
"userName": "SharePoint account user name",
"password": "SharePoint account password",
"ldapUrl": "LDAP URL",
"baseDn": "LDAP base DN",
"ldapUser": "LDAP user name",
"ldapPassword": "LDAP password"
} | Yes |
| `version` | The version of this template that&s currently supported. | `string` | No |
## SharePoint Server 2019 JSON schema
The following is the SharePoint Server 2019 JSON schema:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["SHAREPOINTV2", "SHAREPOINT"]
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"sslCertificatePath": {
"type": "object",
"properties": {
"bucket": {
"type": "string",
"pattern": "^[a-z0-9][\\.\\-a-z0-9]{1,61}[a-z0-9]$",
"minLength": 3,
"maxLength": 63
},
"key": {
"type": "string",
"minLength": 1,
"maxLength": 10240
}
},
"required": ["bucket", "key"]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"minLength": 36,
"maxLength": 36
},
"domain": {
"type": "string"
},
"siteUrls": {
"type": "array",
"items": {
"type": "string",
"pattern": "https://.*"
}
},
"repositoryAdditionalProperties": {
"type": "object",
"properties": {
"authType": {
"type": "string",
"enum": ["OAuth2App", "NTLM", "Kerberos"]
},
"version": {
"type": "string",
"enum": ["Server"]
},
"onPremVersion": {
"type": "string",
"enum": ["", "2013", "2016", "2019", "SubscriptionEdition"]
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": ["authType", "version"]
}
},
"required": ["siteUrls", "domain", "repositoryAdditionalProperties"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"event": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"page": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"file": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"link": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"eventTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"pageTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"linkTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"crawlFiles": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPages": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlEvents": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlComments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlLinks": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAttachments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlListData": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"aclConfiguration": {
"type": "string",
"enum": [
"ACLWithLDAPEmailFmt",
"ACLWithManualEmailFmt",
"ACLWithUsernameFmt"
]
},
"emailDomain": {
"type": "string"
},
"isCrawlLocalGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlAdGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"proxyHost": {
"type": "string"
},
"proxyPort": {
"type": "string"
},
"maxFileSizeInMegaBytes": {
"type": "string"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"type",
"secretArn",
"syncMode",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
## SharePoint Server 2019 JSON schema example
The following is the SharePoint Server 2019 JSON schema example:
```
{
"type": "SHAREPOINTV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-sharepoint-secret",
"enableIdentityCrawler": "true",
"sslCertificatePath": {
"bucket": "my-sharepoint-bucket",
"key": "ssl/cert.pem"
},
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"tenantId": "1234567a-890b-1234-567c-123456789012",
"domain": "mycompany.sharepoint.com",
"siteUrls": [
"https://mycompany.sharepoint.com/sites/TeamSite"
],
"repositoryAdditionalProperties": {
"authType": "OAuth2",
"version": "Server",
"onPremVersion": "2019",
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
},
"repositoryConfigurations": {
"event": {
"fieldMappings": [
{
"indexFieldName": "event_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"page": {
"fieldMappings": [
{
"indexFieldName": "page_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"file": {
"fieldMappings": [
{
"indexFieldName": "file_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"link": {
"fieldMappings": [
{
"indexFieldName": "link_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"eventTitleFilterRegEx": [
"^.*$"
],
"pageTitleFilterRegEx": [
"^.*$"
],
"linkTitleFilterRegEx": [
"^.*$"
],
"inclusionFilePath": [
"documents/"
],
"exclusionFilePath": [
"drafts/"
],
"inclusionFileTypePatterns": [
"*.pdf",
"*.docx"
],
"exclusionFileTypePatterns": [
"*.tmp"
],
"inclusionFileNamePatterns": [
"*report*"
],
"exclusionFileNamePatterns": [
"*draft*"
],
"inclusionOneNoteSectionNamePatterns": [
"*"
],
"exclusionOneNoteSectionNamePatterns": [
"archived"
],
"inclusionOneNotePageNamePatterns": [
"*"
],
"exclusionOneNotePageNamePatterns": [
"test"
],
"crawlFiles": "true",
"crawlPages": "true",
"crawlEvents": "true",
"crawlComments": "true",
"crawlLinks": "true",
"crawlAttachments": "true",
"crawlListData": "false",
"crawlAcl": "true",
"aclConfiguration": "ACLWithUsernameFmt",
"emailDomain": "mycompany.com",
"isCrawlLocalGroupMapping": "false",
"isCrawlAdGroupMapping": "true",
"proxyHost": "proxy.mycompany.com",
"proxyPort": "8080",
"maxFileSizeInMegaBytes": "50"
},
"version": "1.0.0"
}
```
# Connecting Amazon Q Business to SharePoint Server 2019 using AWS CloudFormation
Using the CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
**Topics**
+ [
## SharePoint Server 2019 configuration properties
](#sharepoint-server-2019-configuration-keys)
+ [
## SharePoint Server 2019 JSON schema for using the configuration property with AWS CloudFormation
](#sharepoint-server-2019-cfn-json)
+ [
## SharePoint Server 2019 YAML schema for using the configuration property with AWS CloudFormation
](#sharepoint-server-2019-cfn-yaml)
## SharePoint Server 2019 configuration properties
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has a sub-property called `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-cfn.html) | Yes |
| `tenantId` | The tenant id of your SharePoint account. | `string` OAuth2 series required | Yes |
| `domain` | The domain of your SharePoint account. | `string` | Yes |
| `siteUrls` | The host URLs of your SharePoint account. | `array (string)` Specify the URL in the pattern `https://*` | Yes |
| `repositoryAdditionalProperties` | Additional properties to connect with your repository endpoint. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-cfn.html) | Yes |
| `authType` | The type of authentication you are using: NTLM, Kerberos, or OAuth2App. | `string` | Yes |
| `version` | The SharePoint version you are using: Sever. | `string (Server)` | Yes |
| `onPremVersion` | The SharePoint version that you are using. | `string` Valid values are ` ` (empty), `2013`, `2016`, `2019`, and `SubscriptionEdition`. | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-cfn.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-cfn.html) | A list of objects that map the attributes or field names of your SharePoint Server 2019 pages and assets to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-cfn.html) | No |
| `indexFieldName` | The field name of your SharePoint Server 2019 events, pages, files, links, attachments, or comments. | `string` | Yes |
| `indexFieldType` | The field type of your SharePoint Server 2019 events, pages, files, links, attachments, or comments. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your SharePoint Server 2019 events, pages, files, links, attachments, or comments. | `string` | Yes |
| `dateFieldFormat` | The date format of your SharePoint Server 2019 events, pages, files, links, attachments, or comments. | `string` Specify the date format in the form `yyyy-MM-dd"T"HH:mm:ss"Z"` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-cfn.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-cfn.html) | A list of regular expression patterns to include/exclude specific files in your SharePoint data source. Files that match the patterns are included in the index. File that don&t match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn&t included in the index. | `array (string)` | No |
| `aclConfiguration` | Specifes how your ACL is configured. | `string>` Valid values are `ACLWithLDAPEmailFmt`, `ACLWithManualEmailFmt`, or `ACLWithUsernameFmt`. | No |
| `proxyHost` | The host where the web proxy is required. The host name should be without protocol (http:// or https://). | `string` | Yes |
| `proxyPort` | Port used by the host URL transport protocol. The port number should be a numeric value between 0 and 65535. | `string` | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-cfn.html) | Input TRUE to index. | `boolean` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| `sslCertificatePath` | Configuration information to access the SSL certificate stored in your Amazon S3 bucket. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-cfn.html) | No |
| `bucket` | The name of the Amazon S3 bucket that stores your Microsoft Entra ID (formerly Azure AD) self-signed X.509 certificate. | `string` | Yes |
| `key` | The name of the SSL certificate stored in your Amazon S3 bucket. | `string` | Yes |
| `type` | We recommend that you use SHAREPOINTV2 as your data source type. | `string` Valid values are `SHAREPOINTV2` and `SHAREPOINT`. | Yes |
| `enableIdentityCrawler` | true to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. See [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler) for more information. | `boolean` | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-2019-cfn.html) | Yes |
| `secretARN` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your SharePoint. If you use OAuth2App authentication, provide the client ID, client secret, LDAP URL, LDAP base DN, LDAP user name, and LDAP password. If you use NTLM or Kerberos authentication, provide the user name, password, LDAP URL, Base DN, LDAP user, and LDAP password. | `string` The minimum length is 20 and the maximum length is 2,048 characters. If you use Sharepoint App-Only authentication (`authType` should be `OAuth2App` authentication) the secret must contain a JSON structure with the following keys: {
"clientId": "client ID",
"clientSecret": "client secret",
"ldapUrl": "LDAP URL",
"ldbaseDn": "LDAP base DN",
"ldapUser": "LDAP user name",
"ldapPassword": "LDAP password"
} If you use NTLM authentication or Kerberos authentication, the secret must contain a JSON structure with the following keys: {
"userName": "SharePoint account user name",
"password": "SharePoint account password",
"ldapUrl": "LDAP URL",
"baseDn": "LDAP base DN",
"ldapUser": "LDAP user name",
"ldapPassword": "LDAP password"
} | Yes |
| `version` | The version of this template that&s currently supported. | `string` | No |
## SharePoint Server 2019 JSON schema for using the configuration property with AWS CloudFormation
SharePoint Server 2019 JSON schema
The following is the SharePoint Server 2019 JSON schema and examples for the configuration property for AWS CloudFormation.
**Topics**
+ [
### SharePoint Server 2019 JSON schema for using the configuration property with AWS CloudFormation
](#sharepoint-server-2019-cfn-json-schema)
+ [
### SharePoint Server 2019 JSON schema example for using the configuration property with AWS CloudFormation
](#sharepoint-server-2019-cfn-json-example)
### SharePoint Server 2019 JSON schema for using the configuration property with AWS CloudFormation
SharePoint Server 2019 JSON schema
The following is the SharePoint Server 2019 JSON schema for the configuration property for CloudFormation
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["SHAREPOINTV2", "SHAREPOINT"]
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"sslCertificatePath": {
"type": "object",
"properties": {
"bucket": {
"type": "string",
"pattern": "^[a-z0-9][\\.\\-a-z0-9]{1,61}[a-z0-9]$",
"minLength": 3,
"maxLength": 63
},
"key": {
"type": "string",
"minLength": 1,
"maxLength": 10240
}
},
"required": ["bucket", "key"]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"minLength": 36,
"maxLength": 36
},
"domain": {
"type": "string"
},
"siteUrls": {
"type": "array",
"items": {
"type": "string",
"pattern": "https://.*"
}
},
"repositoryAdditionalProperties": {
"type": "object",
"properties": {
"authType": {
"type": "string",
"enum": ["OAuth2App", "NTLM", "Kerberos"]
},
"version": {
"type": "string",
"enum": ["Server"]
},
"onPremVersion": {
"type": "string",
"enum": ["", "2013", "2016", "2019", "SubscriptionEdition"]
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": ["authType", "version"]
}
},
"required": ["siteUrls", "domain", "repositoryAdditionalProperties"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"event": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"page": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"file": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"link": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"eventTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"pageTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"linkTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"crawlFiles": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPages": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlEvents": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlComments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlLinks": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAttachments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlListData": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"aclConfiguration": {
"type": "string",
"enum": [
"ACLWithLDAPEmailFmt",
"ACLWithManualEmailFmt",
"ACLWithUsernameFmt"
]
},
"emailDomain": {
"type": "string"
},
"isCrawlLocalGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlAdGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"proxyHost": {
"type": "string"
},
"proxyPort": {
"type": "string"
},
"maxFileSizeInMegaBytes": {
"type": "string"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"type",
"secretArn",
"syncMode",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
### SharePoint Server 2019 JSON schema example for using the configuration property with AWS CloudFormation
SharePoint Server 2019 JSON schema example
The following is the SharePoint Server 2019 JSON schema example for the configuration property for CloudFormation
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "CloudFormation SHAREPOINT Data Source Template",
"Resources": {
"DataSourceSharePoint": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": "app12345-1234-1234-1234-123456789012",
"IndexId": "indx1234-1234-1234-1234-123456789012",
"DisplayName": "MySharePointDataSource",
"RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role",
"Configuration": {
"type": "SHAREPOINTV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-sharepoint-secret",
"enableIdentityCrawler": "true",
"sslCertificatePath": {
"bucket": "my-sharepoint-bucket",
"key": "ssl/cert.pem"
},
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"tenantId": "1234567a-890b-1234-567c-123456789012",
"domain": "mycompany.sharepoint.com",
"siteUrls": [
"https://mycompany.sharepoint.com/sites/TeamSite"
],
"repositoryAdditionalProperties": {
"authType": "OAuth2",
"version": "Server",
"onPremVersion": "2019",
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
},
"repositoryConfigurations": {
"event": {
"fieldMappings": [
{
"indexFieldName": "event_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"page": {
"fieldMappings": [
{
"indexFieldName": "page_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"file": {
"fieldMappings": [
{
"indexFieldName": "file_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"link": {
"fieldMappings": [
{
"indexFieldName": "link_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"eventTitleFilterRegEx": [
"^.*$"
],
"pageTitleFilterRegEx": [
"^.*$"
],
"linkTitleFilterRegEx": [
"^.*$"
],
"inclusionFilePath": [
"documents/"
],
"exclusionFilePath": [
"drafts/"
],
"inclusionFileTypePatterns": [
"*.pdf",
"*.docx"
],
"exclusionFileTypePatterns": [
"*.tmp"
],
"inclusionFileNamePatterns": [
"*report*"
],
"exclusionFileNamePatterns": [
"*draft*"
],
"inclusionOneNoteSectionNamePatterns": [
"*"
],
"exclusionOneNoteSectionNamePatterns": [
"archived"
],
"inclusionOneNotePageNamePatterns": [
"*"
],
"exclusionOneNotePageNamePatterns": [
"test"
],
"crawlFiles": "true",
"crawlPages": "true",
"crawlEvents": "true",
"crawlComments": "true",
"crawlLinks": "true",
"crawlAttachments": "true",
"crawlListData": "false",
"crawlAcl": "true",
"aclConfiguration": "ACLWithUsernameFmt",
"emailDomain": "mycompany.com",
"isCrawlLocalGroupMapping": "false",
"isCrawlAdGroupMapping": "true",
"proxyHost": "proxy.mycompany.com",
"proxyPort": "8080",
"maxFileSizeInMegaBytes": "50"
}
}
}
}
}
}
```
## SharePoint Server 2019 YAML schema for using the configuration property with AWS CloudFormation
SharePoint Server 2019 YAML schema
The following is the SharePoint Server 2019 YAML schema and examples for the configuration property for AWS CloudFormation:
**Topics**
+ [
### SharePoint Server 2019 YAML schema for using the configuration property with AWS CloudFormation
](#sharepoint-server-2019-cfn-yaml-schema)
+ [
### SharePoint Server 2019 YAML schema example for using the configuration property with AWS CloudFormation
](#sharepoint-server-2019-cfn-yaml-example)
### SharePoint Server 2019 YAML schema for using the configuration property with AWS CloudFormation
SharePoint Server 2019 YAML schema
The following is the SharePoint Server 2019 YAML schema for the configuration property for CloudFormation.
```
type: object
properties:
type:
type: string
enum:
- SHAREPOINTV2
- SHAREPOINT
syncMode:
type: string
enum:
- FULL_CRAWL
- FORCED_FULL_CRAWL
- CHANGE_LOG
secretArn:
type: string
minLength: 20
maxLength: 2048
enableIdentityCrawler:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
sslCertificatePath:
type: object
properties:
bucket:
type: string
pattern: '^[a-z0-9][\\.\\-a-z0-9]{1,61}[a-z0-9]$'
minLength: 3
maxLength: 63
key:
type: string
minLength: 1
maxLength: 10240
required:
- bucket
- key
connectionConfiguration:
type: object
properties:
repositoryEndpointMetadata:
type: object
properties:
tenantId:
type: string
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
minLength: 36
maxLength: 36
domain:
type: string
siteUrls:
type: array
items:
type: string
pattern: "https://.*"
repositoryAdditionalProperties:
type: object
properties:
authType:
type: string
enum:
- OAuth2App
- NTLM
- Kerberos
version:
type: string
enum:
- Server
onPremVersion:
type: string
enum:
- ""
- "2013"
- "2016"
- "2019"
- SubscriptionEdition
enableDeletionProtection:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
default: false
deletionProtectionThreshold:
type: string
default: "15"
required:
- authType
- version
required:
- siteUrls
- domain
- repositoryAdditionalProperties
required:
- repositoryEndpointMetadata
repositoryConfigurations:
type: object
properties:
event:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
page:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
file:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
link:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
attachment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
comment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
required: []
additionalProperties:
type: object
properties:
eventTitleFilterRegEx:
type: array
items:
type: string
pageTitleFilterRegEx:
type: array
items:
type: string
linkTitleFilterRegEx:
type: array
items:
type: string
inclusionFilePath:
type: array
items:
type: string
exclusionFilePath:
type: array
items:
type: string
inclusionFileTypePatterns:
type: array
items:
type: string
exclusionFileTypePatterns:
type: array
items:
type: string
inclusionFileNamePatterns:
type: array
items:
type: string
exclusionFileNamePatterns:
type: array
items:
type: string
inclusionOneNoteSectionNamePatterns:
type: array
items:
type: string
exclusionOneNoteSectionNamePatterns:
type: array
items:
type: string
inclusionOneNotePageNamePatterns:
type: array
items:
type: string
exclusionOneNotePageNamePatterns:
type: array
items:
type: string
crawlFiles:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlPages:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlEvents:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlComments:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlLinks:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlAttachments:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlListData:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlAcl:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
aclConfiguration:
type: string
enum:
- ACLWithLDAPEmailFmt
- ACLWithManualEmailFmt
- ACLWithUsernameFmt
emailDomain:
type: string
isCrawlLocalGroupMapping:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
isCrawlAdGroupMapping:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
proxyHost:
type: string
proxyPort:
type: string
maxFileSizeInMegaBytes:
type: string
required: []
version:
type: string
anyOf:
- pattern: 1.0.0
required:
- type
- secretArn
- syncMode
- enableIdentityCrawler
- connectionConfiguration
- repositoryConfigurations
- additionalProperties
```
### SharePoint Server 2019 YAML schema example for using the configuration property with AWS CloudFormation
SharePoint Server 2019 JSON schema example
The following is the SharePoint Server 2019 YAML example for the Configuration property for CloudFormation:
```
{
"type": "SHAREPOINTV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-sharepoint-secret",
"enableIdentityCrawler": "true",
"sslCertificatePath": {
"bucket": "my-sharepoint-bucket",
"key": "ssl/cert.pem"
},
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"tenantId": "1234567a-890b-1234-567c-123456789012",
"domain": "mycompany.sharepoint.com",
"siteUrls": [
"https://mycompany.sharepoint.com/sites/TeamSite"
],
"repositoryAdditionalProperties": {
"authType": "OAuth2",
"version": "Server",
"onPremVersion": "2019",
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
},
"repositoryConfigurations": {
"event": {
"fieldMappings": [
{
"indexFieldName": "event_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"page": {
"fieldMappings": [
{
"indexFieldName": "page_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"file": {
"fieldMappings": [
{
"indexFieldName": "file_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"link": {
"fieldMappings": [
{
"indexFieldName": "link_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"eventTitleFilterRegEx": [
"^.*$"
],
"pageTitleFilterRegEx": [
"^.*$"
],
"linkTitleFilterRegEx": [
"^.*$"
],
"inclusionFilePath": [
"documents/"
],
"exclusionFilePath": [
"drafts/"
],
"inclusionFileTypePatterns": [
"*.pdf",
"*.docx"
],
"exclusionFileTypePatterns": [
"*.tmp"
],
"inclusionFileNamePatterns": [
"*report*"
],
"exclusionFileNamePatterns": [
"*draft*"
],
"inclusionOneNoteSectionNamePatterns": [
"*"
],
"exclusionOneNoteSectionNamePatterns": [
"archived"
],
"inclusionOneNotePageNamePatterns": [
"*"
],
"exclusionOneNotePageNamePatterns": [
"test"
],
"crawlFiles": "true",
"crawlPages": "true",
"crawlEvents": "true",
"crawlComments": "true",
"crawlLinks": "true",
"crawlAttachments": "true",
"crawlListData": "false",
"crawlAcl": "true",
"aclConfiguration": "ACLWithUsernameFmt",
"emailDomain": "mycompany.com",
"isCrawlLocalGroupMapping": "false",
"isCrawlAdGroupMapping": "true",
"proxyHost": "proxy.mycompany.com",
"proxyPort": "8080",
"maxFileSizeInMegaBytes": "50"
},
"version": "1.0.0"
}
```
# How Amazon Q Business connector crawls SharePoint Server 2019 ACLs
ACL crawling
When you connect an SharePoint Server 2019 data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your SharePoint Server 2019 instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
To filter using a username, use the **User principal name** from your Azure portal. For example, johnstiles@kendra.onmicrosoft.com.
When you use a SharePoint group for user context filtering, calculate the group ID as follows:
**For local groups**
1. Get the site name. For example, `https://host.onmicrosoft.com/sites/siteName.`
1. Take the SHA256 hash of the site name. For example, `430a6b90503eef95c89295c8999c7981`.
1. Create the group ID by concatenating the SHA256 hash with a vertical bar ( \$1 ) and the group name. For example, if the group name is "local group name", the group ID is the following:
`"430a6b90503eef95c89295c8999c7981 | localGroupName"` (with a space before and after the vertical bar).
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Amazon Q Business SharePoint Server 2019 data source connector field mappings
Field mappings
To help you structure data for retrieval and chat filtering, Amazon Q Business crawls data source document attributes or metadata and maps them to fields in your Amazon Q index.
Amazon Q has reserved fields that it uses when querying your application. When possible, Amazon Q automatically maps these built-in fields to attributes in your data source. If a built-in field doesn't have a default mapping, or if you want to map additional index fields, use the custom field mappings to specify how a data source attribute maps to your Amazon Q application. You create field mappings by editing your data source after your application environment and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes-types.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Sharepoint connector supports the following entities and the associated reserved and custom attributes.
**Important**
If you map any SharePoint Server 2019 field to Amazon Q document title and document body fields, Amazon Q will generate responses from data in the document title and body.
**Note**
You can map any Sharepoint field to the document title or document body Amazon Q reserved/default index fields.
**Topics**
+ [
## Files
](#sharepoint-field-mappings-files)
+ [
## Events
](#sharepoint-field-mappings-events)
+ [
## Pages
](#sharepoint-field-mappings-pages)
+ [
## Links
](#sharepoint-field-mappings-links)
+ [
## Attachments
](#sharepoint-field-mappings-attachments)
## Files
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | \$1document\$1title | Default | String |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| sourceUri | \$1source\$1uri | Default | String |
| checkInComment | sp\$1checkInComment | Custom | String |
| createdAt | \$1created\$1at | Default | Date |
| size | sp\$1sizeLong | Custom | Long (numeric) |
| majorVersion | sp\$1majorVersion | Custom | String |
| uiVersionLabel | sp\$1uiVersionLabel | Custom | String |
| uniqueId | sp\$1uniqueId | Custom | String |
| irmEnabled | sp\$1irmEnabled | Custom | String |
| checkOutType | sp\$1checkOutType | Custom | String |
| author | \$1authors | Default | String list |
| category | \$1category | Default | String |
| modifiedBy | sp\$1modifiedBy | Custom | String |
| level | sp\$1level | Custom | String |
| uiVersion | sp\$1uiVersion | Custom | String |
| contentTag | sp\$1contentTag | Custom | String |
| eTag | sp\$1eTag | Custom | String |
| oneNoteDocument | sp\$1oneNoteDocument | Custom | String |
| oneNoteSection | sp\$1oneNoteSection | Custom | String |
| oneNotePage | sp\$1oneNotePage | Custom | String |
## Events
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | \$1document\$1title | Default | String |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| sourceUri | \$1source\$1uri | Default | String |
| attachments | sp\$1hasAttachments | Custom | String |
| createdDate | \$1created\$1at | Default | Date |
| authorId | sp\$1authorId | Custom | String |
| editorId | sp\$1editorId | Custom | String |
| location | sp\$1location | Custom | String |
| eventDate | sp\$1eventDate | Custom | Date |
| eventEndDate | sp\$1eventEndDate | Custom | Date |
| ifRecurrence | sp\$1ifRecurrence | Custom | String |
| ifAllDayEvent | sp\$1ifAllDayEvent | Custom | String |
| category | \$1category | Default | String |
| eventCategory | sp\$1eventcategory | Custom | String |
## Pages
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| createdDateTime | \$1created\$1at | Default | Date |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| title | \$1document\$1title | Default | String |
| sourceUri | \$1source\$1uri | Default | String |
| firstPublishedDate | sp\$1firstPublishedDate | Custom | Date |
| authorId | sp\$1authorId | Custom | String |
| editorId | sp\$1editorId | Custom | String |
| category | \$1category | Default | String |
## Links
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| createdAt | \$1created\$1at | Default | Date |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| title | \$1document\$1title | Default | String |
| sourceUri | \$1source\$1uri | Default | String |
| fileType | sp\$1fileType | Custom | String |
| fileDirPath | sp\$1fileDirPath | Custom | String |
| firstPublishedDate | sp\$1firstPublishedDate | Custom | Date |
| authorId | sp\$1authorId | Custom | String |
| editorId | sp\$1editorId | Custom | String |
| category | \$1category | Default | String |
| size | sp\$1sizeLong | Custom | Long (numeric) |
## Attachments
| Sharepoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | sp\$1\$1title | Custom | String |
| parentCreatedDate | \$1created\$1at | Default | Date |
| sourceUri | \$1source\$1uri | Default | String |
| parentModifiedDate | \$1last\$1updated\$1at | Custom | Date |
| parentListId | sp\$1parentListId | Custom | String |
| parentTitle | sp\$1parentTitle | Custom | String |
| category | \$1category | Default | String |
# IAM role for Amazon Q Business SharePoint Server 2019 connector
IAM role
**Note**
**(Optional)** If you use **Azure App-Only authentication**, you also need to add permissions for Amazon Q to access the certificate stored in your Amazon S3 bucket.
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Understand error codes in the SharePoint Server 2019 connector
Error Codes
The following table provides information about error codes you may see for the Microsoft SharePoint connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| SPE-5001 | Authentication failed. Configuration might contain wrong credentials. | Provide valid credentials like username, password or client Id, client secret and tenant Id. |
| SPE-5002 | There was a problem while connecting to Host Url and/or Domain. hostUrl and/or domain values might be incorrect. | Provide valid Host URL or Domain. |
| SPE-5003 | Provided URL is incorrect | Provide correct URL. |
| SPE-5004 | Inet Address validation Failed. | Provide valid Inet Address |
| SPE-5005 | Failed : HTTP protocol violation has occurred. | Try running the connector again. |
| SPE-5006 | Cannot connect to proxy. Check the proxy configurations. | Provide valid Proxy configuration details. |
| SPE-5007 | Proxy port is invalid. Check the proxy port. | Provide valid Proxy port. |
| SPE-5008 | Valid SSL Certificate could not be found for connector. | Provide valid SSL certificate. |
| SPE-5009 | There was a problem while connecting to LDAP. Check LDAP configuration. | Provide valid LDAP configuration details. |
| SPE-5100 | There was a problem while retrieving repositoryId. Repository ID might be empty or null. | Ensure that repository Id must not be null or empty. |
| SPE-5101 | There was a problem while retrieving dataSourceIamRoleArn. Data Source IAM Role ARN might be empty or null. | Ensure that dataSourceIamRoleArn must not be null or empty. |
| SPE-5102 | There was a problem while retrieving repository configurations. Repository configurations might be empty or incorrect. | Provide valid repository configurations. |
| SPE-5115 | There was a problem while retrieving field mapping values for event entity. Field mapping values might be empty or incorrect. | Field mapping values for event entity should be correct or non-empty. |
| SPE-5116 | There was a problem while retrieving field mapping values for file entity. Field mapping values might be empty or incorrect. | Field mapping values for file entity should be correct or non-empty. |
| SPE-5117 | There was a problem while retrieving field mapping values for page entity. Field mapping values might be empty or incorrect. | Field mapping values for page entity should be correct or non-empty. |
| SPE-5118 | There was a problem while retrieving field mapping values for link entity. Field mapping values might be empty or incorrect. | Field mapping values for link entity should be correct or non-empty. |
| SPE-5119 | There was a problem while retrieving field mapping values for comment entity. Field mapping values might be empty or incorrect. | Field mapping values for comment entity should be correct or non-empty. |
| SPE-5120 | There was a problem while retrieving field mapping values for attachment entity. Field mapping values might be empty or incorrect. | Field mapping values for attachment entity should be correct or non-empty. |
| SPE-5121 | There was a problem while retrieving values for crawl entities. Values might be empty or incorrect. It should be either true or false. | There might be some incorrect value given in any one of the crawling entities like – null, TRUE or any dummy string. Ensure the value must be non-empty and either true or false. |
| SPE-5122 | There was a problem while retrieving domain. Domain might be empty or null. | Provide Client Id. |
| SPE-5123 | There was a problem while retrieving version. Version might be empty or null. | Provide valid version and it should not be null. |
| SPE-5124 | There was a problem while retrieving authType. Auth-Type might be empty or null. | Ensure AUTH Type in configuration must be not null. |
| SPE-5125 | There was a problem while retrieving clientId. Client ID might be empty or null. | Provide Client Id. |
| SPE-5126 | There was a problem while retrieving clientSecret. Client Secret might be empty or null. | Provide Client Secret. |
| SPE-5127 | There was a problem while retrieving tenantId. Tenant ID might be empty or null. | Provide Tenant Id. |
| SPE-5128 | There was a problem while retrieving siteUrls. Site URLs might be empty or null. | Provide at least one Site Url. |
| SPE-5129 | There was a problem while retrieving password. Password might be empty or null. | Provide password. |
| SPE-5130 | There was a problem while retrieving username.Username might be empty or null. | Provide username. |
| SPE-5131 | There was a problem while retrieving username. Email was invalid. | Provide valid email address. |
| SPE-5132 | There was a problem while retrieving url. This URL was invalid. | Provide a valid URL. |
| SPE-5133 | There was a problem while retrieving s3CertificateName. S3 Certificate Name might be empty or null. | Ensure s3CertificateName is not null or non-empty. |
| SPE-5134 | There was a problem while retrieving s3BucketName. S3 Bucket Name might be empty or null | Ensure s3BucketName is not null or non-empty. |
| SPE-5135 | The provided version was not a valid Sharepoint Connector version. Version should be one of [Online, Server]. | Version should be one of [Online, Server]. |
| SPE-5136 | The provided authType was not a valid Sharepoint Connector authentication method. | Provide valid authType. The value of authType should be one of [Basic, OAuth2Certificate, OAuth2]. |
| SPE-5138 | There was a problem while retrieving onPremVersion. On prem Version might be empty or null | Ensure onPremVersion is not be null or non-empty. |
| SPE-5139 | The provided onPremVersion was not valid Sharepoint on-prem version. On prem version should be one of [2013, 2016, 2019, SubscriptionEdition]. | Provide a valid onPremVersion. On prem version should be one of [2013, 2016, 2019, SubscriptionEdition]. |
| SPE-5140 | There was a problem while retrieving ldapUrl. LDAP Url might be empty or null. | Ensure ldapUrl is not null or empty. |
| SPE-5141 | There was a problem while retrieving baseDn. Base DN might be empty or null. | Ensure baseDn is not be null or empty. |
| SPE-5142 | There was a problem while retrieving privateKey. Private Key might be empty or null. | Please ensure privateKey is not be null or empty. |
| SPE-5144 | There was a problem while retrieving aclConfiguration. ACL Configuration might be empty, null or invalid | Provide valid aclConfiguration. aclConfiguration should be one of [ ACLWithLDAPEmailFmt, ACLWithManualEmailFmt, ACLWithUsernameFmt ]. |
| SPE-5145 | There was a problem while retrieving emailDomain. Email Domain might be empty or null. | Ensure emailDomain is not null or empty. |
| SPE-5146 | There was a problem while retrieving ldapUsername. LDAP Username might be empty or null. | Ensure ldapUser is not null or empty. |
| SPE-5147 | There was a problem while retrieving ldapPassword. LDAP Password might be empty or null. | Ensure ldapPassword is not null or empty. |
| SPE-5149 | The provided siteUrls contain duplicate sites. Remove duplicates. | Ensure SiteUrls must not be the same. |
| SPE-5150 | Invalid Client Id pattern. | Provide the correct client ID. |
| SPE-5151 | Error parsing the field value. Size is over maximum allowed limit. | Ensure the size limit. |
| SPE-5152 | There was a problem while retrieving AD Client ID. AD Client ID should not be empty. | Ensure AD Client Id must be non-empty. |
| SPE-5153 | Invalid AD Client Id pattern. | Provide valid AD Client Id pattern. |
| SPE-5154 | There was a problem while retrieving AD Client Secret. AD Client Secret should not be empty. | Ensure AD Client Secret is non-empty. |
| SPE-5155 | There can't be more than one site for SharePoint on-prem app-only authentication. | Ensure that their must be only single site present for SharePoint on-prem app-only authentication. |
| SPE-5200 | There was a problem while connecting to the URL. | Ensure the siteUrl exists. |
# Connecting SharePoint Server (Subscription Edition) to Amazon Q Business
Microsoft SharePoint Server (Subscription Edition)
Microsoft SharePoint is a collaborative website building service that lets you customize web content and create web pages, web sites, document libraries, and lists. You can connect a SharePoint Server (Subscription Edition) instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
Amazon Q supports Microsoft SharePoint Server (2016, 2019, and Subscription Edition).
**Topics**
+ [
# Known limitations for the Amazon Q Business SharePoint Server (Subscription Edition) connector
](sharepoint-server-subscription-limitations.md)
+ [
# SharePoint Server (Subscription Edition) connector overview
](sharepoint-server-subscription-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to SharePoint Server (Subscription Edition)
](sharepoint-server-subscription-prereqs.md)
+ [
# Connecting Amazon Q Business to SharePoint Server (Subscription Edition) using the console
](sharepoint-server-subscription-console.md)
+ [
# Connecting Amazon Q Business to SharePoint Server (Subscription Edition) using APIs
](sharepoint-server-subscription-api.md)
+ [
# Connecting Amazon Q Business to SharePoint Server (Subscription Edition) using AWS CloudFormation
](sharepoint-server-subscription-cfn.md)
+ [
# How Amazon Q Business connector crawls SharePoint Server (Subscription Edition) ACLs
](sharepoint-server-subscription-user-management.md)
+ [
# Amazon Q Business SharePoint Server (Subscription Edition) data source connector field mappings
](sharepoint-server-subscription-field-mappings.md)
+ [
# IAM role for Amazon Q Business SharePoint Server (Subscription Edition) connector
](sharepoint-server-subscription-iam-role.md)
+ [
# Understand error codes in the SharePoint Server (Subscription Edition) connector
](sharepoint-server-subscription-error-codes.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Amazon Q Business SharePoint Server (Subscription Edition) connector
Known limitations
The SharePoint Server (Subscription Edition) connector has the following known limitations:
+ The Amazon Q SharePoint connector supports custom field mappings only for the **Files** entity.
+ For all SharePoint Server versions, the ACL token must be in lower case. For **Email with Domain from IDP** and **Email ID with Custom Domain** ACL, for example: *user@sharepoint2019.com*. For **Domain\$1User with Domain** ACL, for example: *sharepoint2013\$1user*.
+ If an entity name has a `%` character in its name, the connector will skip these files due to API limitations.
+ OneNote can only be crawled by the connector using a Tenant ID, and with OAuth 2.0, OAuth 2.0 refresh token, or SharePoint App Only authentication activated for SharePoint Online.
+ The connector crawls the first section of a OneNote document using its default name only, even if the document is renamed.
+ The connector crawls links in Subscription Edition, only if **Pages** and **Files** are selected as entities to be crawled in addition to **Links**.
+ The connector crawls only list attachments and comments when **List Data** is also selected as an entity to be crawled.
+ The connector crawls event attachments only when **Events** is also selected as an entity to be crawled.
+ To crawl nested groups using **Identity crawler**, you have to activate Local as well as AD Group Crawling.
+ To use **Identity Crawler** with SharePoint Server (Subscription Edition) to crawl nested groups, you have to enable both Local and AD Group Crawling.
+ Query responses based on AD Group ACLs are not supported for SharePoint Server (Subscription Edition). You need to add users and groups directly to your document permissions list.
+ When Access Control Lists (ACLs) are enabled, the "Sync only new or modified content" option is not available due to SharePoint Server (Subscription Edition) API limitations. We recommend using "Full sync" or "New, modified, or deleted content sync" modes instead, or disable ACLs if you need to use this sync mode.
# SharePoint Server (Subscription Edition) connector overview
Overview
The following table gives an overview of the Amazon Q Business SharePoint Server (Subscription Edition) connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-overview.html)
# Prerequisites for connecting Amazon Q Business to SharePoint Server (Subscription Edition)
Prerequisites
The following page outlines the prerequisites you need to complete before connecting SharePoint Server (Subscription Edition) to Amazon Q, based on the authentication mode of your choice.
**Topics**
+ [
## Prerequisites for using NTLM authentication
](#sharepoint-server-subscription-prereqs-ntlm)
+ [
## Prerequisites for using Kerberos authentication
](#sharepoint-server-subscription-prereqs-kerberos)
+ [
## Prerequisites for using SharePoint App-Only authentication
](#sharepoint-server-subscription-prereqs-app-only)
## Prerequisites for using NTLM authentication
**If you're using NTLM authentication, make sure you've completed the following steps in SharePoint Server (Subscription Edition):**
+ Copied your SharePoint instance URLs. The format for the host URL you enter is *https://yourdomain.sharepoint.com/sites/mysite*. Your URL must start with `https` and contain `sharepoint.com`.
+ Copied the domain name of your SharePoint instance URL.
+ Generated an SSL certificate and uploaded it to an Amazon S3 bucket.
+ Noted the username and password that you use to connect to SharePoint.
**(Optional) If you're using **Email ID with Domain from IDP** to control access to your documents, make sure you've completed the following steps:**
+ Copied your LDAP Server Endpoint (endpoint of LDAP server including protocol and port number). For example: *ldap://example.com:389*.
+ Copied your LDAP Search Base (search base of the LDAP user). For example: *CN=Users,DC=sharepoint,DC=com*.
+ Copied your LDAP username and LDAP password.
**(Optional) If using **Email ID with Custom Domain** for access control, complete the following step:**
+ Noted your custom email domain value—for example: *"amazon.com"*.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your SharePoint Server (Subscription Edition) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
## Prerequisites for using Kerberos authentication
**If you're using Kerberos authentication, make sure you've completed the following steps in SharePoint Server (Subscription Edition):**
+ Copied your SharePoint instance URLs. The format for the host URL you enter is *https://yourdomain.sharepoint.com/sites/mysite*. Your URL must start with `https` and contain `sharepoint.com`.
+ Copied the domain name of your SharePoint instance URL.
+ Generated an SSL certificate and uploaded it to an Amazon S3 bucket.
+ Noted the username and password that you use to connect to SharePoint.
**(Optional) If you're using **Email ID with Domain from IDP** to control access to your documents, make sure you've completed the following steps:**
+ Copied your LDAP Server Endpoint (endpoint of LDAP server including protocol and port number). For example: *ldap://example.com:389*.
+ Copied your LDAP Search Base (search base of the LDAP user). For example: *CN=Users,DC=sharepoint,DC=com*.
+ Copied your LDAP username and LDAP password.
**(Optional) If using **Email ID with Custom Domain** for access control, complete the following step:**
+ Noted your custom email domain value—for example: *"amazon.com"*.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your SharePoint Server (Subscription Edition) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
## Prerequisites for using SharePoint App-Only authentication
**If you're using SharePoint App-Only authentication, make sure you've completed the following steps in SharePoint Server (Subscription Edition):**
+ Copied the SharePoint client ID generated when you registered App Only at Site Level. ClientID format is ClientID@TenantId. For example, *ffa956f3-8f89-44e7-b0e4-49670756342c@888d0b57-69f1-4fb8-957f-e1f0bedf82fe*.
+ Copied the SharePoint client secret generated when you registered App Only at Site Level.
**Important**
**Note: **Because client IDs and client secrets are generated for single sites only when you register SharePoint Server for App Only authentication, only one site URL is supported for SharePoint App Only authentication.
+ Noted the Tenant ID of your SharePoint Server (Subscription Edition) account.
+ Noted your **LDAP Server Endpoint**, **LDAP Search Base**, **LDAP username**, and **LDAP password**.
**Note**
SharePoint App-Only Authentication is *not* supported for SharePoint 2013 version.
**(Optional) If you're using **Email ID with Domain from IDP** to control access to your documents, make sure you've completed the following steps:**
+ Copied your LDAP Server Endpoint (endpoint of LDAP server including protocol and port number). For example: *ldap://example.com:389*.
+ Copied your LDAP Search Base (search base of the LDAP user). For example: *CN=Users,DC=sharepoint,DC=com*.
+ Copied your LDAP username and LDAP password.
**(Optional) If using **Email ID with Custom Domain** for access control, complete the following step:**
+ Noted your custom email domain value—for example: *"amazon.com"*.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your SharePoint Server (Subscription Edition) authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to SharePoint Server (Subscription Edition) using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to SharePoint Server (Subscription Edition) using the AWS Management Console.
**Connecting Amazon Q to SharePoint Server (Subscription Edition)**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **SharePoint** data source to your Amazon Q application.
1. Then, on the **SharePoint Server (Subscription Edition)** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
1. In **Source**, for **Hosting Method** – Choose **SharePoint Server**.
1. **Choose SharePoint Version** – Choose **SharePoint (Subscription Edition)**.
1. **Site URLs specific to your SharePoint repository** – Enter the SharePoint host URLs. The format for the host URLs you enter is *https://yourcompany/sites/mysite*. The URL must start with `https` protocol. Separate URLs with a new line. You can add up to 100 URLs.
1. **Domain** – Enter the SharePoint domain.
1. **SSL certificate location** – Enter the Amazon S3 path to your SSL certificate file.
1. For **Web proxy – *optional*** – Enter the host name (without the `http://` or `https://` protocol), and the port number used by the host URL transport protocol. The numeric value of the port number must be between 0 and 65535.
1. For **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. You can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. For SharePoint Server, you can choose from the following ACL options:
1. **Email ID with Domain from IDP** – Access control is based on email IDs that are extracted from email domains fetched from the underlying identity provider (IdP). You provide the IdP connection details in your Secrets Manager secret during **Authentication**.
1. **Email ID with Custom Domain** – Access control is based on email IDs. Provide the email domain value. For example, *"amazon.com"*. The email domain is used to construct the email ID for access control. You must enter your email domain using **Add Email Domain**.
See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. For **Authentication**, choose between **SharePoint App-Only authentication**, **NTLM authentication**, and **Kerberos authentication**, based on your use case.
1. Enter the following information for both **NTLM authentication** and **Kerberos authentication**:
For **AWS Secrets Manager secret** – Choose an existing secret or create a Secrets Manager secret to store your SharePoint authentication credentials. If you choose to create a secret, an AWS Secrets Manager secret window opens. Enter the following information in the window:
+ **Secret name** – A name for your secret.
+ **Username** – Username for your SharePoint account.
+ **Password** – Password for your SharePoint account.
If using **Email ID with Domain from IDP**, also enter your:
+ **LDAP Server Endpoint** – Endpoint of LDAP server, including protocol and port number. For example: *ldap://example.com:389*.
+ **LDAP Search Base** – Search base of LDAP user. For example: *CN=Users,DC=sharepoint,DC=com*.
+ **LDAP username** – Your LDAP username.
+ **LDAP Password** – Your LDAP password.
1. Enter the following information for **SharePoint App-Only authentication**:
For **AWS Secrets Manager secret** – Choose an existing secret or create a Secrets Manager secret to store your SharePoint authentication credentials. If you choose to create a secret, an AWS Secrets Manager secret window opens. Enter the following information in the window:
+ **Secret name** – A name for your secret.
+ **Client ID** – The SharePoint client ID that you generated when you registered App Only at Site Level. The ClientID format is ClientID@TenantId. For example, *ffa956f3-8f89-44e7-b0e4-49670756342c@888d0b57-69f1-4fb8-957f-e1f0bedf82fe*.
+ **SharePoint client secret** – The SharePoint client secret generated when your register for App Only at Site Level.
**Note:** Because client IDs and client secrets are generated for single sites only when you register SharePoint Server for App Only authentication, only one site URL is supported for SharePoint App Only authentication.
If using **Email ID with Domain from IDP**, also enter your:
+ **LDAP Server Endpoint** – Endpoint of LDAP server, including protocol and port number. For example: *ldap://example.com:389*.
+ **LDAP Search Base** – Search base of LDAP user. For example: *CN=Users,DC=sharepoint,DC=com*.
+ **LDAP username** – Your LDAP user name.
+ **LDAP Password** – Your LDAP password.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-connector.html#sharepoint-server-subscription-iam).
1. In **Sync scope**, choose from the following options :
1. **Select entities** – Choose the entities that you want to crawl. You can select to crawl **All** entities or any combination of **Files**, **Attachments**, **Links**, **Pages**, **Events** and **List Data**.
1. In **Additional configuration – *optional***, for **Entity regex patterns** – Add regular expression patterns for **Links**, **Pages**, and **Events** to include specific entities instead of syncing all your documents.
1. **Regex patterns** – Add regular expression patterns to include or exclude files by **File path**, **File name**, **File type**, **OneNote section name**, and **OneNote page name** instead of syncing all your documents. You can add up to 100 patterns.
**Note**
Any valid regex pattern is supported. For example, if you use the regex `^QBusiness*`, any content starting with the word `QBusiness` followed by any number of characters will be filtered (`QBusiness_doc1` or `QBusiness`, but not `doc1_QBusiness`).
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New or modified content sync** – Sync only new and modified documents.
+ **New, modified, or deleted content sync** – Sync only new, modified, and deleted documents.
For more details, see [Sync mode](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-mode).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
Right after setup, Amazon Q Business automatically tests your connection. This test will ensure that your data source connects properly before you run a sync job.
The test process can take 3-5 minutes. The console will show you if your test is successful. If the test fails, it will display a message.
**Important**
Amazon Q Business can only surface one error at a time. After you correct an error, the test automatically runs again. If there is another error, you will see a message.
# Connecting Amazon Q Business to SharePoint Server (Subscription Edition) using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
**Topics**
+ [
## SharePoint Server (Subscription Edition) configuration properties
](#sharepoint-server-subscription-configuration-keys)
+ [
## SharePoint Server (Subscription Edition) JSON schema
](#sharepoint-server-subscription-json)
+ [
## SharePoint Server (Subscription Edition) JSON schema example
](#sharepoint-server-subscription-api-json-example)
## SharePoint Server (Subscription Edition) configuration properties
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has a sub-property called `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-api.html) | Yes |
| `tenantId` | The tenant id of your SharePoint account. | `string` OAuth2 series required | Yes |
| `domain` | The domain of your SharePoint account. | `string` | Yes |
| `siteUrls` | The host URLs of your SharePoint account. | `array (string)` Specify the URL in the pattern `https://*` | Yes |
| `repositoryAdditionalProperties` | Additional properties to connect with your repository endpoint. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-api.html) | Yes |
| `authType` | The type of authentication you are using: NTLM, Kerberos, or OAuth2App. | `string` | Yes |
| `version` | The SharePoint version you are using: Sever. | `string (Server)` | Yes |
| `onPremVersion` | The SharePoint version that you are using. | `string` Valid values are ` ` (empty), `2013`, `2016`, `2019`, and `SubscriptionEdition`. | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-api.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-api.html) | A list of objects that map the attributes or field names of your SharePoint Server (Subscription Edition) pages and assets to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-api.html) | No |
| `indexFieldName` | The field name of your SharePoint Server (Subscription Edition) events, pages, files, links, attachments, or comments. | `string` | Yes |
| `indexFieldType` | The field type of your SharePoint Server (Subscription Edition) events, pages, files, links, attachments, or comments. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your SharePoint Server (Subscription Edition) events, pages, files, links, attachments, or comments. | `string` | Yes |
| `dateFieldFormat` | The date format of your SharePoint Server (Subscription Edition) events, pages, files, links, attachments, or comments. | `string` Specify the date format in the form `yyyy-MM-dd"T"HH:mm:ss"Z"` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-api.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-api.html) | A list of regular expression patterns to include/exclude specific files in your SharePoint data source. Files that match the patterns are included in the index. File that don&t match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn&t included in the index. | `array (string)` | No |
| `aclConfiguration` | Specifes how your ACL is configured. | `string>` Valid values are `ACLWithLDAPEmailFmt`, `ACLWithManualEmailFmt`, or `ACLWithUsernameFmt`. | No |
| `proxyHost` | The host where the web proxy is required. The host name should be without protocol (http:// or https://). | `string` | Yes |
| `proxyPort` | Port used by the host URL transport protocol. The port number should be a numeric value between 0 and 65535. | `string` | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-api.html) | Input TRUE to index. | `boolean` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| `sslCertificatePath` | Configuration information to access the SSL certificate stored in your Amazon S3 bucket. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-api.html) | No |
| `bucket` | The name of the Amazon S3 bucket that stores your Microsoft Entra ID (formerly Azure AD) self-signed X.509 certificate. | `string` | Yes |
| `key` | The name of the SSL certificate stored in your Amazon S3 bucket. | `string` | Yes |
| `type` | We recommend that you use SHAREPOINTV2 as your data source type. | `string` Valid values are `SHAREPOINTV2` and `SHAREPOINT`. | Yes |
| `enableIdentityCrawler` | true to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. See [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler) for more information. | `boolean` | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-api.html) | Yes |
| `secretARN` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your SharePoint. If you use OAuth2App authentication, provide the client ID, client secret, LDAP URL, LDAP base DN, LDAP user name, and LDAP password. If you use NTLM or Kerberos authentication, provide the user name, password, LDAP URL, Base DN, LDAP user, and LDAP password. | `string` The minimum length is 20 and the maximum length is 2,048 characters. If you use Sharepoint App-Only authentication (`authType` should be `OAuth2App` authentication) the secret must contain a JSON structure with the following keys: {
"clientId": "client ID",
"clientSecret": "client secret",
"ldapUrl": "LDAP URL",
"ldbaseDn": "LDAP base DN",
"ldapUser": "LDAP user name",
"ldapPassword": "LDAP password"
} If you use NTLM authentication or Kerberos authentication, the secret must contain a JSON structure with the following keys: {
"userName": "SharePoint account user name",
"password": "SharePoint account password",
"ldapUrl": "LDAP URL",
"baseDn": "LDAP base DN",
"ldapUser": "LDAP user name",
"ldapPassword": "LDAP password"
} | Yes |
| `version` | The version of this template that&s currently supported. | `string` | No |
## SharePoint Server (Subscription Edition) JSON schema
The following is the SharePoint Server (Subscription Edition) JSON schema:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["SHAREPOINTV2", "SHAREPOINT"]
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"sslCertificatePath": {
"type": "object",
"properties": {
"bucket": {
"type": "string",
"pattern": "^[a-z0-9][\\.\\-a-z0-9]{1,61}[a-z0-9]$",
"minLength": 3,
"maxLength": 63
},
"key": {
"type": "string",
"minLength": 1,
"maxLength": 10240
}
},
"required": ["bucket", "key"]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"minLength": 36,
"maxLength": 36
},
"domain": {
"type": "string"
},
"siteUrls": {
"type": "array",
"items": {
"type": "string",
"pattern": "https://.*"
}
},
"repositoryAdditionalProperties": {
"type": "object",
"properties": {
"authType": {
"type": "string",
"enum": ["OAuth2App", "NTLM", "Kerberos"]
},
"version": {
"type": "string",
"enum": ["Server"]
},
"onPremVersion": {
"type": "string",
"enum": ["", "2013", "2016", "2019", "SubscriptionEdition"]
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": ["authType", "version"]
}
},
"required": ["siteUrls", "domain", "repositoryAdditionalProperties"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"event": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"page": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"file": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"link": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"eventTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"pageTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"linkTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"crawlFiles": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPages": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlEvents": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlComments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlLinks": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAttachments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlListData": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"aclConfiguration": {
"type": "string",
"enum": [
"ACLWithLDAPEmailFmt",
"ACLWithManualEmailFmt",
"ACLWithUsernameFmt"
]
},
"emailDomain": {
"type": "string"
},
"isCrawlLocalGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlAdGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"proxyHost": {
"type": "string"
},
"proxyPort": {
"type": "string"
},
"maxFileSizeInMegaBytes": {
"type": "string"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"type",
"secretArn",
"syncMode",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
## SharePoint Server (Subscription Edition) JSON schema example
The following is the SharePoint Server (Subscription Edition) JSON schema example:
```
{
"type": "SHAREPOINTV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-sharepoint-secret",
"enableIdentityCrawler": "true",
"sslCertificatePath": {
"bucket": "my-sharepoint-bucket",
"key": "ssl/cert.pem"
},
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"tenantId": "1234567a-890b-1234-567c-123456789012",
"domain": "mycompany.sharepoint.com",
"siteUrls": [
"https://mycompany.sharepoint.com/sites/TeamSite"
],
"repositoryAdditionalProperties": {
"authType": "OAuth2",
"version": "Server",
"onPremVersion": "2019",
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
},
"repositoryConfigurations": {
"event": {
"fieldMappings": [
{
"indexFieldName": "event_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"page": {
"fieldMappings": [
{
"indexFieldName": "page_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"file": {
"fieldMappings": [
{
"indexFieldName": "file_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"link": {
"fieldMappings": [
{
"indexFieldName": "link_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"eventTitleFilterRegEx": [
"^.*$"
],
"pageTitleFilterRegEx": [
"^.*$"
],
"linkTitleFilterRegEx": [
"^.*$"
],
"inclusionFilePath": [
"documents/"
],
"exclusionFilePath": [
"drafts/"
],
"inclusionFileTypePatterns": [
"*.pdf",
"*.docx"
],
"exclusionFileTypePatterns": [
"*.tmp"
],
"inclusionFileNamePatterns": [
"*report*"
],
"exclusionFileNamePatterns": [
"*draft*"
],
"inclusionOneNoteSectionNamePatterns": [
"*"
],
"exclusionOneNoteSectionNamePatterns": [
"archived"
],
"inclusionOneNotePageNamePatterns": [
"*"
],
"exclusionOneNotePageNamePatterns": [
"test"
],
"crawlFiles": "true",
"crawlPages": "true",
"crawlEvents": "true",
"crawlComments": "true",
"crawlLinks": "true",
"crawlAttachments": "true",
"crawlListData": "false",
"crawlAcl": "true",
"aclConfiguration": "ACLWithUsernameFmt",
"emailDomain": "mycompany.com",
"isCrawlLocalGroupMapping": "false",
"isCrawlAdGroupMapping": "true",
"proxyHost": "proxy.mycompany.com",
"proxyPort": "8080",
"maxFileSizeInMegaBytes": "50"
},
"version": "1.0.0"
}
```
# Connecting Amazon Q Business to SharePoint Server (Subscription Edition) using AWS CloudFormation
Using the CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
**Topics**
+ [
## SharePoint Server (Subscription Edition) configuration properties
](#sharepoint-server-subscription-configuration-keys)
+ [
## SharePoint Server (Subscription Edition) JSON schema for using the configuration property with AWS CloudFormation
](#sharepoint-server-subscription-cfn-json)
+ [
## SharePoint Server (Subscription Edition) YAML schema for using the configuration property with AWS CloudFormation
](#sharepoint-server-subscription-cfn-yaml)
## SharePoint Server (Subscription Edition) configuration properties
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has a sub-property called `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-cfn.html) | Yes |
| `tenantId` | The tenant id of your SharePoint account. | `string` OAuth2 series required | Yes |
| `domain` | The domain of your SharePoint account. | `string` | Yes |
| `siteUrls` | The host URLs of your SharePoint account. | `array (string)` Specify the URL in the pattern `https://*` | Yes |
| `repositoryAdditionalProperties` | Additional properties to connect with your repository endpoint. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-cfn.html) | Yes |
| `authType` | The type of authentication you are using: NTLM, Kerberos, or OAuth2App. | `string` | Yes |
| `version` | The SharePoint version you are using: Sever. | `string (Server)` | Yes |
| `onPremVersion` | The SharePoint version that you are using. | `string` Valid values are ` ` (empty), `2013`, `2016`, `2019`, and `SubscriptionEdition`. | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-cfn.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-cfn.html) | A list of objects that map the attributes or field names of your SharePoint Server (Subscription Edition) pages and assets to Amazon Q index field names. | `object` These properties have the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-cfn.html) | No |
| `indexFieldName` | The field name of your SharePoint Server (Subscription Edition) events, pages, files, links, attachments, or comments. | `string` | Yes |
| `indexFieldType` | The field type of your SharePoint Server (Subscription Edition) events, pages, files, links, attachments, or comments. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your SharePoint Server (Subscription Edition) events, pages, files, links, attachments, or comments. | `string` | Yes |
| `dateFieldFormat` | The date format of your SharePoint Server (Subscription Edition) events, pages, files, links, attachments, or comments. | `string` Specify the date format in the form `yyyy-MM-dd"T"HH:mm:ss"Z"` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-cfn.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-cfn.html) | A list of regular expression patterns to include/exclude specific files in your SharePoint data source. Files that match the patterns are included in the index. File that don&t match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn&t included in the index. | `array (string)` | No |
| `aclConfiguration` | Specifes how your ACL is configured. | `string>` Valid values are `ACLWithLDAPEmailFmt`, `ACLWithManualEmailFmt`, or `ACLWithUsernameFmt`. | No |
| `proxyHost` | The host where the web proxy is required. The host name should be without protocol (http:// or https://). | `string` | Yes |
| `proxyPort` | Port used by the host URL transport protocol. The port number should be a numeric value between 0 and 65535. | `string` | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-cfn.html) | Input TRUE to index. | `boolean` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| `sslCertificatePath` | Configuration information to access the SSL certificate stored in your Amazon S3 bucket. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-cfn.html) | No |
| `bucket` | The name of the Amazon S3 bucket that stores your Microsoft Entra ID (formerly Azure AD) self-signed X.509 certificate. | `string` | Yes |
| `key` | The name of the SSL certificate stored in your Amazon S3 bucket. | `string` | Yes |
| `type` | We recommend that you use SHAREPOINTV2 as your data source type. | `string` Valid values are `SHAREPOINTV2` and `SHAREPOINT`. | Yes |
| `enableIdentityCrawler` | true to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. See [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler) for more information. | `boolean` | Yes |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/sharepoint-server-subscription-cfn.html) | Yes |
| `secretARN` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your SharePoint. If you use OAuth2App authentication, provide the client ID, client secret, LDAP URL, LDAP base DN, LDAP user name, and LDAP password. If you use NTLM or Kerberos authentication, provide the user name, password, LDAP URL, Base DN, LDAP user, and LDAP password. | `string` The minimum length is 20 and the maximum length is 2,048 characters. If you use Sharepoint App-Only authentication (`authType` should be `OAuth2App` authentication) the secret must contain a JSON structure with the following keys: {
"clientId": "client ID",
"clientSecret": "client secret",
"ldapUrl": "LDAP URL",
"ldbaseDn": "LDAP base DN",
"ldapUser": "LDAP user name",
"ldapPassword": "LDAP password"
} If you use NTLM authentication or Kerberos authentication, the secret must contain a JSON structure with the following keys: {
"userName": "SharePoint account user name",
"password": "SharePoint account password",
"ldapUrl": "LDAP URL",
"baseDn": "LDAP base DN",
"ldapUser": "LDAP user name",
"ldapPassword": "LDAP password"
} | Yes |
| `version` | The version of this template that&s currently supported. | `string` | No |
## SharePoint Server (Subscription Edition) JSON schema for using the configuration property with AWS CloudFormation
SharePoint Server (Subscription Edition) JSON schema
The following is the SharePoint Server (Subscription Edition) JSON schema and examples for the configuration property for AWS CloudFormation.
**Topics**
+ [
### SharePoint Server (Subscription Edition) JSON schema for using the configuration property with AWS CloudFormation
](#sharepoint-server-subscription-cfn-json-schema)
+ [
### SharePoint Server (Subscription Edition) JSON schema example for using the configuration property with AWS CloudFormation
](#sharepoint-server-subscription-cfn-json-example)
### SharePoint Server (Subscription Edition) JSON schema for using the configuration property with AWS CloudFormation
SharePoint Server (Subscription Edition) JSON schema
The following is the SharePoint Server (Subscription Edition) JSON schema for the configuration property for CloudFormation
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["SHAREPOINTV2", "SHAREPOINT"]
},
"syncMode": {
"type": "string",
"enum": ["FULL_CRAWL", "FORCED_FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"sslCertificatePath": {
"type": "object",
"properties": {
"bucket": {
"type": "string",
"pattern": "^[a-z0-9][\\.\\-a-z0-9]{1,61}[a-z0-9]$",
"minLength": 3,
"maxLength": 63
},
"key": {
"type": "string",
"minLength": 1,
"maxLength": 10240
}
},
"required": ["bucket", "key"]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"minLength": 36,
"maxLength": 36
},
"domain": {
"type": "string"
},
"siteUrls": {
"type": "array",
"items": {
"type": "string",
"pattern": "https://.*"
}
},
"repositoryAdditionalProperties": {
"type": "object",
"properties": {
"authType": {
"type": "string",
"enum": ["OAuth2App", "NTLM", "Kerberos"]
},
"version": {
"type": "string",
"enum": ["Server"]
},
"onPremVersion": {
"type": "string",
"enum": ["", "2013", "2016", "2019", "SubscriptionEdition"]
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": ["authType", "version"]
}
},
"required": ["siteUrls", "domain", "repositoryAdditionalProperties"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"event": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"page": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"file": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"link": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"comment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"eventTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"pageTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"linkTitleFilterRegEx": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFilePath": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNoteSectionNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionOneNotePageNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"crawlFiles": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlPages": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlEvents": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlComments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlLinks": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAttachments": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlListData": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"crawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"aclConfiguration": {
"type": "string",
"enum": [
"ACLWithLDAPEmailFmt",
"ACLWithManualEmailFmt",
"ACLWithUsernameFmt"
]
},
"emailDomain": {
"type": "string"
},
"isCrawlLocalGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlAdGroupMapping": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"proxyHost": {
"type": "string"
},
"proxyPort": {
"type": "string"
},
"maxFileSizeInMegaBytes": {
"type": "string"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"type",
"secretArn",
"syncMode",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
```
### SharePoint Server (Subscription Edition) JSON schema example for using the configuration property with AWS CloudFormation
SharePoint Server (Subscription Edition) JSON schema example
The following is the SharePoint Server (Subscription Edition) JSON schema example for the configuration property for CloudFormation
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "CloudFormation SHAREPOINT Data Source Template",
"Resources": {
"DataSourceSharePoint": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": "app12345-1234-1234-1234-123456789012",
"IndexId": "indx1234-1234-1234-1234-123456789012",
"DisplayName": "MySharePointDataSource",
"RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role",
"Configuration": {
"type": "SHAREPOINTV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-sharepoint-secret",
"enableIdentityCrawler": "true",
"sslCertificatePath": {
"bucket": "my-sharepoint-bucket",
"key": "ssl/cert.pem"
},
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"tenantId": "1234567a-890b-1234-567c-123456789012",
"domain": "mycompany.sharepoint.com",
"siteUrls": [
"https://mycompany.sharepoint.com/sites/TeamSite"
],
"repositoryAdditionalProperties": {
"authType": "OAuth2",
"version": "Server",
"onPremVersion": "2019",
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
},
"repositoryConfigurations": {
"event": {
"fieldMappings": [
{
"indexFieldName": "event_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"page": {
"fieldMappings": [
{
"indexFieldName": "page_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"file": {
"fieldMappings": [
{
"indexFieldName": "file_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"link": {
"fieldMappings": [
{
"indexFieldName": "link_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"eventTitleFilterRegEx": [
"^.*$"
],
"pageTitleFilterRegEx": [
"^.*$"
],
"linkTitleFilterRegEx": [
"^.*$"
],
"inclusionFilePath": [
"documents/"
],
"exclusionFilePath": [
"drafts/"
],
"inclusionFileTypePatterns": [
"*.pdf",
"*.docx"
],
"exclusionFileTypePatterns": [
"*.tmp"
],
"inclusionFileNamePatterns": [
"*report*"
],
"exclusionFileNamePatterns": [
"*draft*"
],
"inclusionOneNoteSectionNamePatterns": [
"*"
],
"exclusionOneNoteSectionNamePatterns": [
"archived"
],
"inclusionOneNotePageNamePatterns": [
"*"
],
"exclusionOneNotePageNamePatterns": [
"test"
],
"crawlFiles": "true",
"crawlPages": "true",
"crawlEvents": "true",
"crawlComments": "true",
"crawlLinks": "true",
"crawlAttachments": "true",
"crawlListData": "false",
"crawlAcl": "true",
"aclConfiguration": "ACLWithUsernameFmt",
"emailDomain": "mycompany.com",
"isCrawlLocalGroupMapping": "false",
"isCrawlAdGroupMapping": "true",
"proxyHost": "proxy.mycompany.com",
"proxyPort": "8080",
"maxFileSizeInMegaBytes": "50"
}
}
}
}
}
}
```
## SharePoint Server (Subscription Edition) YAML schema for using the configuration property with AWS CloudFormation
SharePoint Server (Subscription Edition) YAML schema
The following is the SharePoint Server (Subscription Edition) YAML schema and examples for the configuration property for AWS CloudFormation:
**Topics**
+ [
### SharePoint Server (Subscription Edition) YAML schema for using the configuration property with AWS CloudFormation
](#sharepoint-server-subscription-cfn-yaml-schema)
+ [
### SharePoint Server (Subscription Edition) YAML schema example for using the configuration property with AWS CloudFormation
](#sharepoint-server-subscription-cfn-yaml-example)
### SharePoint Server (Subscription Edition) YAML schema for using the configuration property with AWS CloudFormation
SharePoint Server (Subscription Edition) YAML schema
The following is the SharePoint Server (Subscription Edition) YAML schema for the configuration property for CloudFormation.
```
type: object
properties:
type:
type: string
enum:
- SHAREPOINTV2
- SHAREPOINT
syncMode:
type: string
enum:
- FULL_CRAWL
- FORCED_FULL_CRAWL
- CHANGE_LOG
secretArn:
type: string
minLength: 20
maxLength: 2048
enableIdentityCrawler:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
sslCertificatePath:
type: object
properties:
bucket:
type: string
pattern: '^[a-z0-9][\\.\\-a-z0-9]{1,61}[a-z0-9]$'
minLength: 3
maxLength: 63
key:
type: string
minLength: 1
maxLength: 10240
required:
- bucket
- key
connectionConfiguration:
type: object
properties:
repositoryEndpointMetadata:
type: object
properties:
tenantId:
type: string
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
minLength: 36
maxLength: 36
domain:
type: string
siteUrls:
type: array
items:
type: string
pattern: "https://.*"
repositoryAdditionalProperties:
type: object
properties:
authType:
type: string
enum:
- OAuth2App
- NTLM
- Kerberos
version:
type: string
enum:
- Server
onPremVersion:
type: string
enum:
- ""
- "2013"
- "2016"
- "2019"
- SubscriptionEdition
enableDeletionProtection:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
default: false
deletionProtectionThreshold:
type: string
default: "15"
required:
- authType
- version
required:
- siteUrls
- domain
- repositoryAdditionalProperties
required:
- repositoryEndpointMetadata
repositoryConfigurations:
type: object
properties:
event:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
page:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
file:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
link:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
attachment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
comment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
required: []
additionalProperties:
type: object
properties:
eventTitleFilterRegEx:
type: array
items:
type: string
pageTitleFilterRegEx:
type: array
items:
type: string
linkTitleFilterRegEx:
type: array
items:
type: string
inclusionFilePath:
type: array
items:
type: string
exclusionFilePath:
type: array
items:
type: string
inclusionFileTypePatterns:
type: array
items:
type: string
exclusionFileTypePatterns:
type: array
items:
type: string
inclusionFileNamePatterns:
type: array
items:
type: string
exclusionFileNamePatterns:
type: array
items:
type: string
inclusionOneNoteSectionNamePatterns:
type: array
items:
type: string
exclusionOneNoteSectionNamePatterns:
type: array
items:
type: string
inclusionOneNotePageNamePatterns:
type: array
items:
type: string
exclusionOneNotePageNamePatterns:
type: array
items:
type: string
crawlFiles:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlPages:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlEvents:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlComments:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlLinks:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlAttachments:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlListData:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
crawlAcl:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
aclConfiguration:
type: string
enum:
- ACLWithLDAPEmailFmt
- ACLWithManualEmailFmt
- ACLWithUsernameFmt
emailDomain:
type: string
isCrawlLocalGroupMapping:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
isCrawlAdGroupMapping:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
proxyHost:
type: string
proxyPort:
type: string
maxFileSizeInMegaBytes:
type: string
required: []
version:
type: string
anyOf:
- pattern: 1.0.0
required:
- type
- secretArn
- syncMode
- enableIdentityCrawler
- connectionConfiguration
- repositoryConfigurations
- additionalProperties
```
### SharePoint Server (Subscription Edition) YAML schema example for using the configuration property with AWS CloudFormation
SharePoint Server (Subscription Edition) JSON schema example
The following is the SharePoint Server (Subscription Edition) YAML example for the Configuration property for CloudFormation:
```
{
"type": "SHAREPOINTV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-sharepoint-secret",
"enableIdentityCrawler": "true",
"sslCertificatePath": {
"bucket": "my-sharepoint-bucket",
"key": "ssl/cert.pem"
},
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"tenantId": "1234567a-890b-1234-567c-123456789012",
"domain": "mycompany.sharepoint.com",
"siteUrls": [
"https://mycompany.sharepoint.com/sites/TeamSite"
],
"repositoryAdditionalProperties": {
"authType": "OAuth2",
"version": "Server",
"onPremVersion": "2019",
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
},
"repositoryConfigurations": {
"event": {
"fieldMappings": [
{
"indexFieldName": "event_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"page": {
"fieldMappings": [
{
"indexFieldName": "page_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"file": {
"fieldMappings": [
{
"indexFieldName": "file_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"link": {
"fieldMappings": [
{
"indexFieldName": "link_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"comment": {
"fieldMappings": [
{
"indexFieldName": "comment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"eventTitleFilterRegEx": [
"^.*$"
],
"pageTitleFilterRegEx": [
"^.*$"
],
"linkTitleFilterRegEx": [
"^.*$"
],
"inclusionFilePath": [
"documents/"
],
"exclusionFilePath": [
"drafts/"
],
"inclusionFileTypePatterns": [
"*.pdf",
"*.docx"
],
"exclusionFileTypePatterns": [
"*.tmp"
],
"inclusionFileNamePatterns": [
"*report*"
],
"exclusionFileNamePatterns": [
"*draft*"
],
"inclusionOneNoteSectionNamePatterns": [
"*"
],
"exclusionOneNoteSectionNamePatterns": [
"archived"
],
"inclusionOneNotePageNamePatterns": [
"*"
],
"exclusionOneNotePageNamePatterns": [
"test"
],
"crawlFiles": "true",
"crawlPages": "true",
"crawlEvents": "true",
"crawlComments": "true",
"crawlLinks": "true",
"crawlAttachments": "true",
"crawlListData": "false",
"crawlAcl": "true",
"aclConfiguration": "ACLWithUsernameFmt",
"emailDomain": "mycompany.com",
"isCrawlLocalGroupMapping": "false",
"isCrawlAdGroupMapping": "true",
"proxyHost": "proxy.mycompany.com",
"proxyPort": "8080",
"maxFileSizeInMegaBytes": "50"
},
"version": "1.0.0"
}
```
# How Amazon Q Business connector crawls SharePoint Server (Subscription Edition) ACLs
ACL crawling
When you connect an SharePoint Server (Subscription Edition) data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your SharePoint Server (Subscription Edition) instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
To filter using a username, use the **User principal name** from your Azure portal. For example, johnstiles@kendra.onmicrosoft.com.
When you use a SharePoint group for user context filtering, calculate the group ID as follows:
**For local groups**
1. Get the site name. For example, `https://host.onmicrosoft.com/sites/siteName.`
1. Take the SHA256 hash of the site name. For example, `430a6b90503eef95c89295c8999c7981`.
1. Create the group ID by concatenating the SHA256 hash with a vertical bar ( \$1 ) and the group name. For example, if the group name is "local group name", the group ID is the following:
`"430a6b90503eef95c89295c8999c7981 | localGroupName"` (with a space before and after the vertical bar).
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Amazon Q Business SharePoint Server (Subscription Edition) data source connector field mappings
Field mappings
To help you structure data for retrieval and chat filtering, Amazon Q Business crawls data source document attributes or metadata and maps them to fields in your Amazon Q index.
Amazon Q has reserved fields that it uses when querying your application. When possible, Amazon Q automatically maps these built-in fields to attributes in your data source. If a built-in field doesn't have a default mapping, or if you want to map additional index fields, use the custom field mappings to specify how a data source attribute maps to your Amazon Q application. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes-types.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q SharePoint connector supports the following entities and the associated reserved and custom attributes.
**Important**
If you map any SharePoint Server (Subscription Edition) field to Amazon Q document title and document body fields, Amazon Q will generate responses from data in the document title and body.
**Note**
You can map any SharePoint field to the document title or document body Amazon Q reserved/default index fields.
**Topics**
+ [
## Files
](#sharepoint-field-mappings-files)
+ [
## Events
](#sharepoint-field-mappings-events)
+ [
## Pages
](#sharepoint-field-mappings-pages)
+ [
## Links
](#sharepoint-field-mappings-links)
+ [
## Attachments
](#sharepoint-field-mappings-attachments)
+ [
## Comments
](#sharepoint-field-mappings-comments)
## Files
| SharePoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | sp\$1title | Custom | String |
| sourceUri | \$1source\$1uri | Default | String |
| checkInComment | sp\$1checkInComment | Custom | String |
| size | sp\$1sizeLong | Custom | Long (numeric) |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| createdAt | \$1created\$1at | Default | Date |
| author | \$1authors | Default | String list |
| majorVersion | sp\$1majorVersion | Custom | String |
| uiVersionLabel | sp\$1uiVersionLabel | Custom | String |
| uniqueId | sp\$1uniqueId | Custom | String |
| irmEnabled | sp\$1irmEnabled | Custom | String |
| checkOutType | sp\$1checkOutType | Custom | String |
| category | \$1category | Default | String |
| modifiedBy | sp\$1modifiedBy | Custom | String |
| level | sp\$1level | Custom | String |
| uiVersion | sp\$1uiVersion | Custom | String |
| contentTag | sp\$1contentTag | Custom | String |
| eTag | sp\$1eTag | Custom | String |
| oneNoteDocument | sp\$1oneNoteDocument | Custom | String |
| oneNoteSection | sp\$1oneNoteSection | Custom | String |
| oneNotePage | sp\$1oneNotePage | Custom | String |
## Events
| SharePoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | sp\$1title | Custom | String |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| sourceUri | \$1source\$1uri | Default | String |
| attachments | sp\$1hasAttachments | Custom | String |
| createdDate | \$1created\$1at | Default | Date |
| authorId | sp\$1authorId | Custom | String |
| editorId | sp\$1editorId | Custom | String |
| location | sp\$1location | Custom | String |
| eventDate | sp\$1eventDate | Custom | Date |
| eventEndDate | sp\$1eventEndDate | Custom | Date |
| ifRecurrence | sp\$1ifRecurrence | Custom | String |
| ifAllDayEvent | sp\$1ifAllDayEvent | Custom | String |
| category | \$1category | Default | String |
| eventCategory | sp\$1eventcategory | Custom | String |
## Pages
| SharePoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| createdDateTime | \$1created\$1at | Default | Date |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| title | sp\$1title | Custom | String |
| sourceUri | \$1source\$1uri | Default | String |
| firstPublishedDate | sp\$1firstPublishedDate | Custom | Date |
| authorId | sp\$1authorId | Custom | String |
| editorId | sp\$1editorId | Custom | String |
| category | \$1category | Default | String |
## Links
| SharePoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| createdAt | \$1created\$1at | Default | Date |
| lastModifiedDateTime | \$1last\$1updated\$1at | Default | Date |
| title | sp\$1title | Custom | String |
| sourceUri | \$1source\$1uri | Default | String |
| fileType | sp\$1fileType | Custom | String |
| fileDirPath | sp\$1fileDirPath | Custom | String |
| firstPublishedDate | sp\$1firstPublishedDate | Custom | Date |
| authorId | sp\$1authorId | Custom | String |
| editorId | sp\$1editorId | Custom | String |
| category | \$1category | Default | String |
| size | sp\$1sizeLong | Custom | Long (numeric) |
## Attachments
| SharePoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| title | sp\$1\$1title | Custom | String |
| parentCreatedDate | \$1created\$1at | Default | Date |
| sourceUri | \$1source\$1uri | Default | String |
| parentModifiedDate | \$1last\$1updated\$1at | Custom | Date |
| parentListId | sp\$1parentListId | Custom | String |
| parentTitle | sp\$1parentTitle | Custom | String |
| category | \$1category | Default | String |
## Comments
| SharePoint field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| createdDateTime | \$1created\$1at | Default | Date |
| likedBy | sp\$1likedBy | Custom | String |
| sourceUri | \$1source\$1uri | Custom | String |
| isReply | sp\$1isReply | Custom | String |
| author | \$1authors | Default | String list |
| listId | sp\$1listId | Custom | String |
| category | \$1category | Default | String |
| replyCount | sp\$1replyCount | Custom | String |
| parentTitle | sp\$1parentTitle | Custom | String |
# IAM role for Amazon Q Business SharePoint Server (Subscription Edition) connector
IAM role
**Note**
**(Optional)** If you use **Azure App-Only authentication**, you also need to add permissions for Amazon Q to access the certificate stored in your Amazon S3 bucket.
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ Permission to access the SSL certificate stored in your Amazon S3 bucket.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Understand error codes in the SharePoint Server (Subscription Edition) connector
Error Codes
The following table provides information about error codes you may see for the Microsoft SharePoint connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| SPE-5001 | Authentication failed. Configuration might contain wrong credentials. | Provide valid credentials like username, password or client Id, client secret and tenant Id. |
| SPE-5002 | There was a problem while connecting to Host Url and/or Domain. hostUrl and/or domain values might be incorrect. | Provide valid Host URL or Domain. |
| SPE-5003 | Provided URL is incorrect | Provide correct URL. |
| SPE-5004 | Inet Address validation Failed. | Provide valid Inet Address |
| SPE-5005 | Failed : HTTP protocol violation has occurred. | Try running the connector again. |
| SPE-5006 | Cannot connect to proxy. Check the proxy configurations. | Provide valid Proxy configuration details. |
| SPE-5007 | Proxy port is invalid. Check the proxy port. | Provide valid Proxy port. |
| SPE-5008 | Valid SSL Certificate could not be found for connector. | Provide valid SSL certificate. |
| SPE-5009 | There was a problem while connecting to LDAP. Check LDAP configuration. | Provide valid LDAP configuration details. |
| SPE-5100 | There was a problem while retrieving repositoryId. Repository ID might be empty or null. | Ensure that repository Id must not be null or empty. |
| SPE-5101 | There was a problem while retrieving dataSourceIamRoleArn. Data Source IAM Role ARN might be empty or null. | Ensure that dataSourceIamRoleArn must not be null or empty. |
| SPE-5102 | There was a problem while retrieving repository configurations. Repository configurations might be empty or incorrect. | Provide valid repository configurations. |
| SPE-5115 | There was a problem while retrieving field mapping values for event entity. Field mapping values might be empty or incorrect. | Field mapping values for event entity should be correct or non-empty. |
| SPE-5116 | There was a problem while retrieving field mapping values for file entity. Field mapping values might be empty or incorrect. | Field mapping values for file entity should be correct or non-empty. |
| SPE-5117 | There was a problem while retrieving field mapping values for page entity. Field mapping values might be empty or incorrect. | Field mapping values for page entity should be correct or non-empty. |
| SPE-5118 | There was a problem while retrieving field mapping values for link entity. Field mapping values might be empty or incorrect. | Field mapping values for link entity should be correct or non-empty. |
| SPE-5119 | There was a problem while retrieving field mapping values for comment entity. Field mapping values might be empty or incorrect. | Field mapping values for comment entity should be correct or non-empty. |
| SPE-5120 | There was a problem while retrieving field mapping values for attachment entity. Field mapping values might be empty or incorrect. | Field mapping values for attachment entity should be correct or non-empty. |
| SPE-5121 | There was a problem while retrieving values for crawl entities. Values might be empty or incorrect. It should be either true or false. | There might be some incorrect value given in any one of the crawling entities like – null, TRUE or any dummy string. Ensure the value must be non-empty and either true or false. |
| SPE-5122 | There was a problem while retrieving domain. Domain might be empty or null. | Provide Client Id. |
| SPE-5123 | There was a problem while retrieving version. Version might be empty or null. | Provide valid version and it should not be null. |
| SPE-5124 | There was a problem while retrieving authType. Auth-Type might be empty or null. | Ensure AUTH Type in configuration must be not null. |
| SPE-5125 | There was a problem while retrieving clientId. Client ID might be empty or null. | Provide Client Id. |
| SPE-5126 | There was a problem while retrieving clientSecret. Client Secret might be empty or null. | Provide Client Secret. |
| SPE-5127 | There was a problem while retrieving tenantId. Tenant ID might be empty or null. | Provide Tenant Id. |
| SPE-5128 | There was a problem while retrieving siteUrls. Site URLs might be empty or null. | Provide at least one Site Url. |
| SPE-5129 | There was a problem while retrieving password. Password might be empty or null. | Provide password. |
| SPE-5130 | There was a problem while retrieving username.Username might be empty or null. | Provide username. |
| SPE-5131 | There was a problem while retrieving username. Email was invalid. | Provide valid email address. |
| SPE-5132 | There was a problem while retrieving url. This URL was invalid. | Provide a valid URL. |
| SPE-5133 | There was a problem while retrieving s3CertificateName. S3 Certificate Name might be empty or null. | Ensure s3CertificateName is not null or non-empty. |
| SPE-5134 | There was a problem while retrieving s3BucketName. S3 Bucket Name might be empty or null | Ensure s3BucketName is not null or non-empty. |
| SPE-5135 | The provided version was not a valid Sharepoint Connector version. Version should be one of [Online, Server]. | Version should be one of [Online, Server]. |
| SPE-5136 | The provided authType was not a valid Sharepoint Connector authentication method. | Provide valid authType. The value of authType should be one of [Basic, OAuth2Certificate, OAuth2]. |
| SPE-5138 | There was a problem while retrieving onPremVersion. On prem Version might be empty or null | Ensure onPremVersion is not be null or non-empty. |
| SPE-5139 | The provided onPremVersion was not valid Sharepoint on-prem version. On prem version should be one of [2013, 2016, 2019, SubscriptionEdition]. | Provide a valid onPremVersion. On prem version should be one of [2013, 2016, 2019, SubscriptionEdition]. |
| SPE-5140 | There was a problem while retrieving ldapUrl. LDAP Url might be empty or null. | Ensure ldapUrl is not null or empty. |
| SPE-5141 | There was a problem while retrieving baseDn. Base DN might be empty or null. | Ensure baseDn is not be null or empty. |
| SPE-5142 | There was a problem while retrieving privateKey. Private Key might be empty or null. | Please ensure privateKey is not be null or empty. |
| SPE-5144 | There was a problem while retrieving aclConfiguration. ACL Configuration might be empty, null or invalid | Provide valid aclConfiguration. aclConfiguration should be one of [ ACLWithLDAPEmailFmt, ACLWithManualEmailFmt, ACLWithUsernameFmt ]. |
| SPE-5145 | There was a problem while retrieving emailDomain. Email Domain might be empty or null. | Ensure emailDomain is not null or empty. |
| SPE-5146 | There was a problem while retrieving ldapUsername. LDAP Username might be empty or null. | Ensure ldapUser is not null or empty. |
| SPE-5147 | There was a problem while retrieving ldapPassword. LDAP Password might be empty or null. | Ensure ldapPassword is not null or empty. |
| SPE-5149 | The provided siteUrls contain duplicate sites. Remove duplicates. | Ensure SiteUrls must not be the same. |
| SPE-5150 | Invalid Client Id pattern. | Provide the correct client ID. |
| SPE-5151 | Error parsing the field value. Size is over maximum allowed limit. | Ensure the size limit. |
| SPE-5152 | There was a problem while retrieving AD Client ID. AD Client ID should not be empty. | Ensure AD Client Id must be non-empty. |
| SPE-5153 | Invalid AD Client Id pattern. | Provide valid AD Client Id pattern. |
| SPE-5154 | There was a problem while retrieving AD Client Secret. AD Client Secret should not be empty. | Ensure AD Client Secret is non-empty. |
| SPE-5155 | There can't be more than one site for SharePoint on-prem app-only authentication. | Ensure that their must be only single site present for SharePoint on-prem app-only authentication. |
| SPE-5200 | There was a problem while connecting to the URL. | Ensure the siteUrl exists. |
# Connecting Microsoft Teams to Amazon Q Business
Microsoft Teams
You can connect Microsoft Teams to Amazon Q Business to index and search your team's messages, channel posts, and files. This connection enables your organization to find relevant information from Teams conversations and shared content through your Amazon Q web experience.
Use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API to create the connection.
**Topics**
+ [
# Microsoft Teams connector versions
](teams-versions.md)
+ [
# Known limitations for the Microsoft Teams connector
](teams-limitations.md)
+ [
# Microsoft Teams connector overview
](teams-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Microsoft Teams
](teams-prereqs.md)
+ [
# Connecting using the latest Microsoft Teams connector (Console)
](teams-console-new.md)
+ [
# Connecting using the legacy Microsoft Teams connector (Console)
](teams-console-original.md)
+ [
# Connecting Amazon Q Business to Microsoft Teams using APIs
](teams-api.md)
+ [
# Connecting Amazon Q Business to Microsoft Teams using AWS CloudFormation
](teams-cfn.md)
+ [
# How Amazon Q Business connector crawls Microsoft Teams ACLs
](teams-user-management.md)
+ [
# Microsoft Teams data source connector field mappings
](teams-field-mappings.md)
+ [
# IAM role for Microsoft Teams connector
](teams-iam-role.md)
+ [
# Troubleshooting your Microsoft Teams connector
](teams-troubleshooting.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Microsoft Teams connector versions
Connector versions
You can choose between two Microsoft Teams connector versions:
## Latest Microsoft Teams connector (recommended)
Latest connector
**Note**
The latest connector provides improved accuracy. We recommend using the latest connector for new implementations. The legacy connector remains available if you need specific features not yet supported in the latest connector.
The latest Microsoft Teams connector offers a simplified configuration experience with the following features:
+ Chat messages and channel posts syncing
+ Simplified sync scope without channel wiki
+ Date range filters only
+ Enhanced UI layout with improved spacing
+ Application-level permissions for enhanced security
+ Automatic crawling of ACL and identity information
## Legacy Microsoft Teams connector
Legacy connector
The legacy Microsoft Teams connector provides full-featured configuration with advanced options:
+ Complete sync scope including calendar meetings, channel wiki, and attachments
+ Advanced filtering options with team names, channel names, and attachment sections
+ Custom field mappings for metadata extraction
+ Configurable sync modes and VPC settings
+ Regex pattern matching for complex attachment filtering
+ Manual ACL and identity crawling configuration
# Known limitations for the Microsoft Teams connector
Known limitations
**Note**
**Original version notice:** We recommend using the new connector for improved performance and retrieval quality. The following limitations apply only to the original connector version.
When you use the test data source connection feature, the Microsoft Teams connector has a potential issue when testing Identity Crawler. If testing takes longer than five minutes, Amazon Q skips testing Identity Crawler and moves on to the next test. A connection error with Identity Crawler is possible even after finishing connection testing.
The Microsoft Teams connector has these known limitations:
+ When you enable Access Control Lists (ACLs), the "Sync only new or modified content" option is not available due to Microsoft Teams API limitations. Use "Full sync" or "New, modified, or deleted content sync" modes instead, or disable ACLs to use this sync mode.
# Microsoft Teams connector overview
Overview
The following table shows the Amazon Q Business Microsoft Teams connector features and capabilities.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-overview.html)
# Prerequisites for connecting Amazon Q Business to Microsoft Teams
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Microsoft Teams, make sure you have:**
+ Created a Microsoft Teams account in Office 365.
+ Copied your Microsoft 365 Tenant ID. You can find your Tenant ID in the Properties of your Azure Active Directory Portal. You need this URL to allow Amazon Q to connect with your Microsoft Teams data source. For more information, see [Register a Microsoft Entra app and create a service principal](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#sign-in-to-the-application) on the Microsoft website.
+ Configured an OAuth 2.0 credential token containing a client ID and client secret. For more information, see [Azure documentation on managing access tokens for Teams](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/manage-teams-identity?pivots=programming-language-csharp) on the Microsoft website.
+ Added the necessary permissions. You can choose to add all permissions, or you can limit the scope by selecting fewer permissions based on which entities you want to crawl. *(Application level permissions required for new connector)* All permissions must be at *application* level, not delegated. The following table shows permissions by corresponding entity.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-prereqs.html)
+ Generated Microsoft Teams OAuth 2.0 credentials containing a client ID, client secret, username, and password. You need these credentials to authenticate Amazon Q to access Microsoft Teams.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Microsoft Teams authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting using the latest Microsoft Teams connector (Console)
Using the latest connector (Console)
The latest Microsoft Teams connector provides a simplified configuration experience with essential features. Use this procedure to connect Amazon Q Business to Microsoft Teams using the latest connector.
**To connect Amazon Q to Microsoft Teams using the latest connector**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Microsoft Teams** data source to your Amazon Q application.
1. Then, on the **Microsoft Teams** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
1. **Tenant ID** – Enter your Tenant ID.
**Note**
Your Microsoft Tenant ID is a globally unique identifier that's necessary to configure each connector instance. Your Tenant ID is different from your organization name or domain and can be found in the **Properties** section of your Azure Active Directory Portal.
1. For **Authentication**, in **AWS Secrets Manager** – Choose between **Create and add new secret** and **Use existing secrets**.
1. If you choose **Use existing secrets**, select an existing secret.
If you choose **Create and add a new secret**, enter the following information in the **Create AWS Secrets Manager secret** section:
1. **Secret name** – A name for your secret.
1. **Client ID** – Enter the Client ID you generated after registering your application for use. You can find this Client ID in **App registrations** in your Azure Active Directory Portal.
1. **Client Secret** – Enter the client secret that you generated from your Teams account.
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-connector.html#teams-iam).
1. **Sync scope** – Choose the content you want to sync.
1. Choose **All** to crawl and sync all your documents.
1. For **Chat**, choose from the following options:
1. Choose **Chat** to crawl and sync all chats. If you choose this option, Amazon Q Business also crawls **Chat messages** by default.
1. Choose **Chat messages** to crawl and sync only all chat messages.
1. For **Teams**, choose from the following options:
1. Choose **Teams** to crawl and sync all teams. If you choose this option, Amazon Q Business also crawls **Channel posts** by default.
1. Choose **Channel posts** to crawl and sync only all channel posts.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Additional configuration – *optional***, configure the following simplified options:
+ **Date Range** – Enter the date range for which the connector will crawl your content. End date is optional. Rolling window options available: Last [X] Days/Weeks/Months.
**Note**
**Simplified configuration:** The latest connector automatically handles entity selection with ACL enabled by default to keep the configuration simple and reliable.
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting using the legacy Microsoft Teams connector (Console)
Using the legacy connector (Console)
The legacy Microsoft Teams connector provides comprehensive configuration options including entity type selection, field mappings, and VPC settings. Use this procedure to connect Amazon Q Business to Microsoft Teams using the legacy connector.
**To connect Amazon Q to Microsoft Teams using the legacy connector**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Microsoft Teams** data source to your Amazon Q application.
1. Then, on the **Microsoft Teams** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
1. **Tenant ID** – Enter your Tenant ID.
**Note**
Your Microsoft Tenant ID is a globally unique identifier that's necessary to configure each connector instance. Your Tenant ID is different from your organization name or domain and can be found in the **Properties** section of your Azure Active Directory Portal.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. For **Authentication**, in **AWS Secrets Manager** – Choose between **Create and add new secret** and **Use existing secrets**.
1. If you choose **Use existing secrets**, select an existing secret.
If you choose **Create and add a new secret**, enter the following information in the **Create AWS Secrets Manager secret** section:
1. **Secret name** – A name for your secret.
1. **Client ID** – Enter the Client ID you generated after registering your application for use. You can find this Client ID in **App registrations** in your Azure Active Directory Portal.
1. **Client Secret** – Enter the client secret that you generated from your Teams account.
1. **Payment model** – Choose the payment model associated with your Microsoft Teams account. Model A payment models are restricted to licensing and payment models that require security compliance. Model B payment models are suitable for licensing and payment models that don't require security compliance.
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-connector.html#teams-iam).
1. **Sync scope** – Choose the content you want to sync.
1. Choose **All** to crawl and sync all your documents.
1. For **Chat**, choose from the following options:
1. Choose **Chat** to crawl and sync all chats. If you choose this option, Amazon Q Business also crawls **Chat messages** and **Chat files** by default.
1. Choose **Chat messages** to crawl and sync only all chat messages.
1. Choose **Chat files** to crawl and sync only all chat files.
1. For **Teams**, choose from the following options:
1. Choose **Teams** to crawl and sync all teams. If you choose this option, Amazon Q Business also crawls **Channel posts**, **Channel files and folders** and **Channel wiki** by default.
1. Choose **Channel posts** to crawl and sync only all channel posts.
1. Choose **Channel files and folders** to crawl and sync only all channel files and folders.
1. Choose **Channel wiki** to crawl and sync only all channel wikis.
1. For **Calendar**, choose from the following options:
1. Choose **Calendar** to crawl and sync your calendar. If you choose this option, Amazon Q Business also crawls **Meetings**, **Meeting chats**, **Meeting files** and **Meeting notes** by default.
1. Choose **Meetings** to crawl and sync only all meetings.
1. Choose **Meeting chats** to crawl and sync only all meeting chats.
1. Choose **Meeting files** to crawl and sync only all meeting files.
1. Choose **Meeting notes** to crawl and sync only all meeting notes.
1. **Multi-media content configuration – optional** – To enable content extraction from embedded images and visuals in documents, choose **Visual content in documents**.
To extract audio transcriptions and video content, enable processing for the following file types:
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB.
1. In **Additional configuration – *optional***, configure the following comprehensive options:
+ **Calendar crawling** – Enter the date range for which the connector will crawl your calendar content.
+ **User email** – Enter the emails of the users you want to include in your application.
+ **Team names** – Add patterns to include or exclude teams found in Microsoft Teams from your application.
+ **Channel names** – Add patterns to include or exclude channels found in Microsoft Teams from your application.
+ **Attachment regex patterns** – Add regular expression patterns to include or exclude certain attachment for all supported entities. You can add up to 100 patterns.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Microsoft Teams using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
**Topics**
+ [
# Connecting Amazon Q Business to Microsoft Teams (new connector) using APIs
](teams-new-api.md)
+ [
# Connecting Amazon Q Business to Microsoft Teams (Original connector) using APIs
](teams-original-api.md)
# Connecting Amazon Q Business to Microsoft Teams (new connector) using APIs
Using the API (new connector)
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
## Microsoft Teams new connector JSON schema
The following is the Microsoft Teams new connector JSON schema:
```
{
"$schema": "https://json-schema.org/draft-07/schema#",
"$id": "https://amazonaws.com/plato/connector/configuration/msteams",
"title": "Microsoft Teams Configuration Schema",
"description": "JSON Schema for Microsoft Teams data connector configuration based on Smithy model",
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"MSTEAMSV2"
],
"description": "The connector type identifier"
},
"connectionConfiguration": {
"type": "object",
"description": "Configuration for connecting to Microsoft Teams",
"properties": {
"tenantId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[4][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"minLength": 36,
"maxLength": 36,
"description": "Microsoft Teams tenant ID in UUID v4 format"
},
"secretArn": {
"type": "string",
"pattern": "^arn:[a-z0-9-\\.]{1,63}:[a-z0-9-\\.]{0,63}:[a-z0-9-\\.]{0,63}:[a-z0-9-\\.]{0,63}:[^/].{0,1023}$",
"description": "ARN of the AWS Secrets Manager secret containing authentication credentials"
}
},
"required": ["tenantId", "secretArn"],
"additionalProperties": false
},
"filterConfiguration": {
"type": "object",
"description": "Configuration for filtering data based on date ranges",
"properties": {
"startDateFilter": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$",
"description": "Start date for filtering data in ISO 8601 format"
},
"endDateFilter": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$",
"description": "End date for filtering data in ISO 8601 format"
}
},
"additionalProperties": false
},
"dataEntityConfiguration": {
"type": "object",
"description": "Configuration for specifying which data entities to crawl",
"properties": {
"crawlChatMessages": {
"type": "boolean",
"description": "Whether to crawl chat messages from Microsoft Teams"
},
"crawlChannelPosts": {
"type": "boolean",
"description": "Whether to crawl channel posts from Microsoft Teams"
}
},
"additionalProperties": false
},
"deletionProtectionConfiguration": {
"type": "object",
"description": "Configuration for deletion protection settings",
"properties": {
"enableDeletionProtection": {
"type": "boolean",
"description": "Whether to enable deletion protection"
},
"deletionProtectionThreshold": {
"type": "string",
"pattern": "^(100|[1-9][0-9]?)$",
"description": "Deletion protection threshold as a percentage (1-100)"
}
},
"additionalProperties": false
}
},
"required": [
"type",
"connectionConfiguration",
"dataEntityConfiguration"
],
"additionalProperties": false,
"examples": [
{
"type": "MSTEAMSV2",
"connectionConfiguration": {
"tenantId": "12345678-1234-4123-8123-123456789012",
"secretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:msteams-credentials-AbCdEf"
},
"filterConfiguration": {
"startDateFilter": "2024-01-01T00:00:00Z",
"endDateFilter": "2024-12-31T23:59:59Z"
},
"dataEntityConfiguration": {
"crawlChatMessages": true,
"crawlChannelPosts": true
},
"deletionProtectionConfiguration": {
"enableDeletionProtection": true,
"deletionProtectionThreshold": "10"
}
}
]
}
```
The following table provides information about important JSON keys to configure for the new Microsoft Teams connector.
| Configuration | Description |
| --- | --- |
| type | The type of data source. Must be MSTEAMSV2 for the new Teams connector. |
| connectionConfiguration | Configuration information for connecting to the Teams data source. |
| tenantId | The Microsoft Teams tenant ID in UUID v4 format. |
| secretArn | The Amazon Resource Name (ARN) of a Secrets Manager secret that contains the key-value pairs required to connect to your Microsoft Teams. |
| dataEntityConfiguration | Configuration for the types of data entities to crawl from Teams. |
| crawlChatMessages | A Boolean value to specify whether to crawl chat messages. Set to true to include chat messages in the crawl, or false to exclude them. |
| crawlChannelPosts | A Boolean value to specify whether to crawl channel posts. Set to true to include channel posts in the crawl, or false to exclude them. |
| filterConfiguration | Optional configuration for filtering content during the crawl process. |
| startDateFilter | Specify the start date for filtering content. Only content created on or after this date will be crawled. Format: ISO 8601 date-time format. |
| endDateFilter | Specify the end date for filtering content. Only content created on or before this date will be crawled. Format: ISO 8601 date-time format. |
| deletionProtectionConfiguration | Optional configuration to protect against accidental deletion of large amounts of content. |
| enableDeletionProtection | A Boolean value to enable deletion protection. When enabled, the connector will not delete more than the specified threshold of documents in a single sync. |
| deletionProtectionThreshold | The maximum percentage of documents that can be deleted in a single sync when deletion protection is enabled. Specify as a string containing a number from 1 to 100. |
# Connecting Amazon Q Business to Microsoft Teams (Original connector) using APIs
Using the API (Original connector)
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
## Microsoft Teams configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for endpoint for the data source. | `object` This property has the following sub-property: `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-property: `tenantId`. | Yes |
| `tenantId` | The Microsoft 365 tenant ID. You can find your tenant ID in the Properties of your Azure Active Directory Portal. | `string` The string must be 36 characters long and in in the pattern: ^[0-9a-f]\$18\$1-[0-9a-f]\$14\$1-[0-9a-f]\$14\$1-[0-9a-f]\$14\$1-[0-9a-f]\$112\$1\$1 | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-original-api.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-original-api.html) | A list of objects that map the attributes or field names of your Microsoft Teams content to Amazon Q index field names. | `object` These properties have the following sub-properties: `indexFieldName`, `indexFieldType`, `dataSourceFieldName`, and `dateFieldFormat`. | No |
| `indexFieldName` | The field name of your Microsoft Teams assets. | `string` | Yes |
| `indexFieldType` | The field type of your Microsoft Teams assets. | `string` The allowed values are `STRING`, `STRING_LIST`, `DATE`, and `LONG`. | Yes |
| `dataSourceFieldName` | The data source field name of your Microsoft Teams assets. | `string` | Yes |
| `dateFieldFormat` | The date format of your Microsoft Teams assets. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-original-api.html) | Yes |
| `isCrawlAcl` | Specify true to crawl access control information from documents. Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. | `boolean` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| `fieldForUserId` | Specify the field to use for UserId for ACL crawling. | `string` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-original-api.html) | Specify true to index this content in your Microsoft Teams data source. | `boolean` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-original-api.html) | A list of regular expression patterns to include specific content in your Microsoft Teams data source. Content that matches the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-original-api.html) | A list of regular expression patterns to exclude specific content in your Microsoft Teams data source. Content that matches the patterns are excluded from the index. Content that doesn't match the patterns are included in the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-original-api.html) | You can choose to configure a startCalendarDateTime and endCalendarDateTime parameters so that the Microsoft Teams connector crawls content based on a specific date range. | `string` Specify the date in the form `^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$)` | No |
| `paymentModel` | Specifies what type of payment model to use with your Teams data source. Model A payment models are restricted to licensing and payment models that require security compliance. Model B payment models are suitable for licensing and payment models that don't require security compliance. | `string` Valid values are `A`, `B`, and `Evaluation Mode`. | No |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-original-api.html) | Yes |
| `secretARN` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Microsoft Teams. | `string` The secret must contain a JSON structure with the following keys: {
"clientId": String,
"clientSecret": String
} | Yes |
| `type` | The type of data source. Specify MSTEAMS as your data source type. | `string` | Yes |
| `enableIdentityCrawler` | `true` to activate identity crawler.Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). | `boolean` | No |
| `version` | The version of this template that's currently supported. | `string` | No |
## Microsoft Teams JSON schema
The following is the Microsoft Teams JSON schema:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"pattern": "MSTEAMS"
},
"syncMode": {
"type": "string",
"enum": ["FORCED_FULL_CRAWL", "FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"minLength": 36,
"maxLength": 36
}
},
"required": ["tenantId"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"chatMessage": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"chatAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"channelPost": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"channelWiki": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"channelAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"meetingChat": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"meetingFile": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"meetingNote": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"calendarMeeting": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"paymentModel": {
"type": "string",
"enum": ["A", "B", "Evaluation Mode"]
},
"inclusionTeamNameFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionTeamNameFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionChannelNameFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionChannelNameFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionUserEmailFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"isCrawlChatMessage": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlChatAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlChannelPost": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlChannelAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlChannelWiki": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlCalendarMeeting": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlMeetingChat": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlMeetingFile": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlMeetingNote": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"startCalendarDateTime": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
},
{
"type": "string",
"pattern": ""
}
]
},
"endCalendarDateTime": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
},
{
"type": "string",
"pattern": ""
}
]
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"type",
"syncMode",
"secretArn",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
}
```
## Microsoft Teams JSON schema example
The following is the Microsoft Teams JSON schema example:
```
{
"type": "MSTEAMS",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-teams-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"tenantId": "123e4567-e89b-12d3-a456-426614174000"
}
},
"repositoryConfigurations": {
"chatMessage": {
"fieldMappings": [
{
"indexFieldName": "message_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"chatAttachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"channelPost": {
"fieldMappings": [
{
"indexFieldName": "post_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"channelWiki": {
"fieldMappings": [
{
"indexFieldName": "wiki_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"channelAttachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"meetingChat": {
"fieldMappings": [
{
"indexFieldName": "meeting_chat_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"meetingFile": {
"fieldMappings": [
{
"indexFieldName": "meeting_file_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"meetingNote": {
"fieldMappings": [
{
"indexFieldName": "meeting_note_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"calendarMeeting": {
"fieldMappings": [
{
"indexFieldName": "calendar_meeting_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"isCrawlAcl": "true",
"maxFileSizeInMegaBytes": "50",
"fieldForUserId": "user_id",
"paymentModel": "A",
"inclusionTeamNameFilter": ["TeamA", "TeamB"],
"exclusionTeamNameFilter": ["TeamC"],
"inclusionChannelNameFilter": ["Channel1", "Channel2"],
"exclusionChannelNameFilter": ["Channel3"],
"inclusionFileNamePatterns": ["*.docx", "*.pdf"],
"exclusionFileNamePatterns": ["*.tmp"],
"inclusionFileTypePatterns": ["image/png", "image/jpeg"],
"exclusionFileTypePatterns": ["application/octet-stream"],
"inclusionUserEmailFilter": ["user@example.com"],
"isCrawlChatMessage": "true",
"isCrawlChatAttachment": "true",
"isCrawlChannelPost": "true",
"isCrawlChannelAttachment": "true",
"isCrawlChannelWiki": "true",
"isCrawlCalendarMeeting": "true",
"isCrawlMeetingChat": "true",
"isCrawlMeetingFile": "true",
"isCrawlMeetingNote": "true",
"startCalendarDateTime": "2023-01-01T00:00:00Z",
"endCalendarDateTime": "2023-12-31T23:59:59Z",
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
```
# Connecting Amazon Q Business to Microsoft Teams using AWS CloudFormation
Using the CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
## Microsoft Teams configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for endpoint for the data source. | `object` This property has the following sub-property: `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-property: `tenantId`. | Yes |
| `tenantId` | The Microsoft 365 tenant ID. You can find your tenant ID in the Properties of your Azure Active Directory Portal. | `string` The string must be 36 characters long and in in the pattern: ^[0-9a-f]\$18\$1-[0-9a-f]\$14\$1-[0-9a-f]\$14\$1-[0-9a-f]\$14\$1-[0-9a-f]\$112\$1\$1 | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-cfn.html) | Yes |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-cfn.html) | A list of objects that map the attributes or field names of your Microsoft Teams content to Amazon Q index field names. | `object` These properties have the following sub-properties: `indexFieldName`, `indexFieldType`, `dataSourceFieldName`, and `dateFieldFormat`. | No |
| `indexFieldName` | The field name of your Microsoft Teams assets. | `string` | Yes |
| `indexFieldType` | The field type of your Microsoft Teams assets. | `string` The allowed values are `STRING`, `STRING_LIST`, `DATE`, and `LONG`. | Yes |
| `dataSourceFieldName` | The data source field name of your Microsoft Teams assets. | `string` | Yes |
| `dateFieldFormat` | The date format of your Microsoft Teams assets. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-cfn.html) | Yes |
| `isCrawlAcl` | Specify true to crawl access control information from documents. Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. | `boolean` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| `fieldForUserId` | Specify the field to use for UserId for ACL crawling. | `string` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-cfn.html) | Specify true to index this content in your Microsoft Teams data source. | `boolean` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-cfn.html) | A list of regular expression patterns to include specific content in your Microsoft Teams data source. Content that matches the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-cfn.html) | A list of regular expression patterns to exclude specific content in your Microsoft Teams data source. Content that matches the patterns are excluded from the index. Content that doesn't match the patterns are included in the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-cfn.html) | You can choose to configure a startCalendarDateTime and endCalendarDateTime parameters so that the Microsoft Teams connector crawls content based on a specific date range. | `string` Specify the date in the form `^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$)` | No |
| `paymentModel` | Specifies what type of payment model to use with your Teams data source. Model A payment models are restricted to licensing and payment models that require security compliance. Model B payment models are suitable for licensing and payment models that don't require security compliance. | `string` Valid values are `A`, `B`, and `Evaluation Mode`. | No |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/teams-cfn.html) | Yes |
| `secretARN` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Microsoft Teams. | `string` The secret must contain a JSON structure with the following keys: {
"clientId": String,
"clientSecret": String
} | Yes |
| `type` | The type of data source. Specify MSTEAMS as your data source type. | `string` | Yes |
| `enableIdentityCrawler` | `true` to activate identity crawler.Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). | `boolean` | No |
| `version` | The version of this template that's currently supported. | `string` | No |
## Microsoft Teams JSON schema for using the CloudFormation
## Microsoft Teams JSON schema for using the configuration property with AWS CloudFormation
Microsoft Teams JSONMicrosoft Teams JSON schema
The following is the Microsoft Teams JSON schema and examples for the configuration property for AWS CloudFormation.
**Topics**
+ [
### Microsoft Teams JSON schema for using the configuration property with AWS CloudFormation
](#teams-cfn-json-schema)
+ [
### Microsoft Teams JSON schema example for using the configuration property with AWS CloudFormation
](#teams-cfn-json-example)
### Microsoft Teams JSON schema for using the configuration property with AWS CloudFormation
Microsoft Teams JSON schema
The following is the Microsoft Teams JSON schema for the configuration property for CloudFormation
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"pattern": "MSTEAMS"
},
"syncMode": {
"type": "string",
"enum": ["FORCED_FULL_CRAWL", "FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"minLength": 36,
"maxLength": 36
}
},
"required": ["tenantId"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"chatMessage": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"chatAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"channelPost": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"channelWiki": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"channelAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"meetingChat": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"meetingFile": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"meetingNote": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"calendarMeeting": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"paymentModel": {
"type": "string",
"enum": ["A", "B", "Evaluation Mode"]
},
"inclusionTeamNameFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionTeamNameFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionChannelNameFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionChannelNameFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionUserEmailFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"isCrawlChatMessage": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlChatAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlChannelPost": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlChannelAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlChannelWiki": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlCalendarMeeting": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlMeetingChat": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlMeetingFile": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlMeetingNote": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"startCalendarDateTime": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
},
{
"type": "string",
"pattern": ""
}
]
},
"endCalendarDateTime": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
},
{
"type": "string",
"pattern": ""
}
]
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"type",
"syncMode",
"secretArn",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
}
```
### Microsoft Teams JSON schema example for using the configuration property with AWS CloudFormation
Microsoft Teams JSON schema example
The following is the Microsoft Teams JSON schema example for the configuration property for CloudFormation
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "CloudFormation MSTEAMS Data Source Template",
"Resources": {
"DataSourceMSTeams": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": "app12345-1234-1234-1234-123456789012",
"IndexId": "indx1234-1234-1234-1234-123456789012",
"DisplayName": "MyMSTeamsDataSource",
"RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role",
"Configuration": {
"type": "MSTEAMS",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-teams-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"tenantId": "123e4567-e89b-12d3-a456-426614174000"
}
},
"repositoryConfigurations": {
"chatMessage": {
"fieldMappings": [
{
"indexFieldName": "message_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"chatAttachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"channelPost": {
"fieldMappings": [
{
"indexFieldName": "post_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"channelWiki": {
"fieldMappings": [
{
"indexFieldName": "wiki_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"channelAttachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"meetingChat": {
"fieldMappings": [
{
"indexFieldName": "meeting_chat_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"meetingFile": {
"fieldMappings": [
{
"indexFieldName": "meeting_file_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"meetingNote": {
"fieldMappings": [
{
"indexFieldName": "meeting_note_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"calendarMeeting": {
"fieldMappings": [
{
"indexFieldName": "calendar_meeting_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"isCrawlAcl": "true",
"maxFileSizeInMegaBytes": "50",
"fieldForUserId": "user_id",
"paymentModel": "A",
"inclusionTeamNameFilter": ["TeamA", "TeamB"],
"exclusionTeamNameFilter": ["TeamC"],
"inclusionChannelNameFilter": ["Channel1", "Channel2"],
"exclusionChannelNameFilter": ["Channel3"],
"inclusionFileNamePatterns": ["*.docx", "*.pdf"],
"exclusionFileNamePatterns": ["*.tmp"],
"inclusionFileTypePatterns": ["image/png", "image/jpeg"],
"exclusionFileTypePatterns": ["application/octet-stream"],
"inclusionUserEmailFilter": ["user@example.com"],
"isCrawlChatMessage": "true",
"isCrawlChatAttachment": "true",
"isCrawlChannelPost": "true",
"isCrawlChannelAttachment": "true",
"isCrawlChannelWiki": "true",
"isCrawlCalendarMeeting": "true",
"isCrawlMeetingChat": "true",
"isCrawlMeetingFile": "true",
"isCrawlMeetingNote": "true",
"startCalendarDateTime": "2023-01-01T00:00:00Z",
"endCalendarDateTime": "2023-12-31T23:59:59Z",
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
}
}
}
}
```
## Microsoft Teams YAML schema for using the configuration property with AWS CloudFormation
Microsoft Teams YAML schema
The following is the Microsoft Teams YAML schema and examples for the configuration property for AWS CloudFormation:
**Topics**
+ [
### Microsoft Teams YAML schema for using the configuration property with AWS CloudFormation
](#teams-cfn-yaml-schema)
+ [
### Microsoft Teams YAML schema example for using the configuration property with AWS CloudFormation
](#teams-cfn-yaml-example)
### Microsoft Teams YAML schema for using the configuration property with AWS CloudFormation
Microsoft Teams YAML schema
The following is the Microsoft Teams YAML schema for the configuration property for CloudFormation.
```
type: object
properties:
type:
type: string
pattern: MSTEAMS
syncMode:
type: string
enum:
- FORCED_FULL_CRAWL
- FULL_CRAWL
- CHANGE_LOG
secretArn:
type: string
minLength: 20
maxLength: 2048
enableIdentityCrawler:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
connectionConfiguration:
type: object
properties:
repositoryEndpointMetadata:
type: object
properties:
tenantId:
type: string
pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
minLength: 36
maxLength: 36
required:
- tenantId
required:
- repositoryEndpointMetadata
repositoryConfigurations:
type: object
properties:
chatMessage:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
chatAttachment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
channelPost:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
channelWiki:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
channelAttachment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
meetingChat:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
meetingFile:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
meetingNote:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
calendarMeeting:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
additionalProperties:
type: object
properties:
isCrawlAcl:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
maxFileSizeInMegaBytes:
type: string
fieldForUserId:
type: string
paymentModel:
type: string
enum:
- A
- B
- Evaluation Mode
inclusionTeamNameFilter:
type: array
items:
type: string
exclusionTeamNameFilter:
type: array
items:
type: string
inclusionChannelNameFilter:
type: array
items:
type: string
exclusionChannelNameFilter:
type: array
items:
type: string
inclusionFileNamePatterns:
type: array
items:
type: string
exclusionFileNamePatterns:
type: array
items:
type: string
inclusionFileTypePatterns:
type: array
items:
type: string
exclusionFileTypePatterns:
type: array
items:
type: string
inclusionUserEmailFilter:
type: array
items:
type: string
isCrawlChatMessage:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlChatAttachment:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlChannelPost:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlChannelAttachment:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlChannelWiki:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlCalendarMeeting:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlMeetingChat:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlMeetingFile:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlMeetingNote:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
startCalendarDateTime:
anyOf:
- type: string
pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
- type: string
pattern: ""
endCalendarDateTime:
anyOf:
- type: string
pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
- type: string
pattern: ""
enableDeletionProtection:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
default: false
deletionProtectionThreshold:
type: string
default: "15"
required: []
version:
type: string
anyOf:
- pattern: "1.0.0"
required:
- connectionConfiguration
- repositoryConfigurations
- syncMode
- additionalProperties
- secretArn
- type
```
### Microsoft Teams YAML schema example for using the configuration property with AWS CloudFormation
Microsoft Teams JSON schema example
The following is the Microsoft Teams YAML example for the Configuration property for CloudFormation:
```
AWSTemplateFormatVersion: "2010-09-09"
Description: CloudFormation MSTEAMS Data Source Template
Resources:
DataSourceMSTeams:
Type: AWS::QBusiness::DataSource
Properties:
ApplicationId: app12345-1234-1234-1234-123456789012
IndexId: indx1234-1234-1234-1234-123456789012
DisplayName: MyMSTeamsDataSource
RoleArn: arn:aws:iam::123456789012:role/qbusiness-data-source-role
Configuration:
type: MSTEAMS
syncMode: FULL_CRAWL
secretArn: arn:aws:secretsmanager:us-west-2:123456789012:secret:my-teams-secret
enableIdentityCrawler: "true"
connectionConfiguration:
repositoryEndpointMetadata:
tenantId: 123e4567-e89b-12d3-a456-426614174000
repositoryConfigurations:
chatMessage:
fieldMappings:
- indexFieldName: message_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
chatAttachment:
fieldMappings:
- indexFieldName: attachment_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
channelPost:
fieldMappings:
- indexFieldName: post_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
channelWiki:
fieldMappings:
- indexFieldName: wiki_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
channelAttachment:
fieldMappings:
- indexFieldName: attachment_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
meetingChat:
fieldMappings:
- indexFieldName: meeting_chat_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
meetingFile:
fieldMappings:
- indexFieldName: meeting_file_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
meetingNote:
fieldMappings:
- indexFieldName: meeting_note_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
calendarMeeting:
fieldMappings:
- indexFieldName: calendar_meeting_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
additionalProperties:
isCrawlAcl: "true"
maxFileSizeInMegaBytes: "50"
fieldForUserId: user_id
paymentModel: A
inclusionTeamNameFilter:
- TeamA
- TeamB
exclusionTeamNameFilter:
- TeamC
inclusionChannelNameFilter:
- Channel1
- Channel2
exclusionChannelNameFilter:
- Channel3
inclusionFileNamePatterns:
- "*.docx"
- "*.pdf"
exclusionFileNamePatterns:
- "*.tmp"
inclusionFileTypePatterns:
- image/png
- image/jpeg
exclusionFileTypePatterns:
- application/octet-stream
inclusionUserEmailFilter:
- user@example.com
isCrawlChatMessage: "true"
isCrawlChatAttachment: "true"
isCrawlChannelPost: "true"
isCrawlChannelAttachment: "true"
isCrawlChannelWiki: "true"
isCrawlCalendarMeeting: "true"
isCrawlMeetingChat: "true"
isCrawlMeetingFile: "true"
isCrawlMeetingNote: "true"
startCalendarDateTime: "2023-01-01T00:00:00Z"
endCalendarDateTime: "2023-12-31T23:59:59Z"
enableDeletionProtection: "false"
deletionProtectionThreshold: "15"
```
**Note**
ACL crawling is available for both new and original Microsoft Teams connector versions.
# How Amazon Q Business connector crawls Microsoft Teams ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
Microsoft Teams content is categorized into Chats, Channels, and Calendar. Chats support one-on-one and group conversations with attachments, which can be filtered using email domains or regex rules. Channels are structured within Microsoft Teams and can be Standard (open to all team members), Shared (accessible to team members and invited external users), or Private (restricted to specific members). Calendars facilitate meeting scheduling and management, supporting attachments and OneNote tabs.
When you connect a Microsoft Teams data source to Amazon Q Business, Amazon Q Business makes a copy of these resources and creates an index that can be used to respond to user prompts and queries. Additionally, the connector crawls ACL information attached to a document (user and group information) from your Microsoft Teams instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
**Identity Crawling**: Amazon Q Business synchronizes both local and federated users/groups. Federated groups are synced outside Amazon Q, and their memberships are not stored. Identities are canonicalized by converting all letters to lowercase to prevent duplication issues, meaning "TestUser" and "testuser" are treated as the same. When a user is deleted, their permissions are not inherited by a newly created user with the same name, ensuring secure access management. Once a user is marked as disabled in Microsoft Teams, after the next sync users will no longer have access to search or retrieve previously crawled data, including calendar meetings.
Users can configure the connector to include filters for channel posts and attachments. Team and Channel name can be included and excluded. Also, we can add regular expression to include and exclude filters for attachments. Private channels are restricted to specific members within a team. Shared and private channels have their own ACLs, enabling more granular permission management.
**Permission Inheritance**: Chats, Channels and Calendar inherit permissions from the root or the group while attachments inherit from their parent entity (chat, channel, or calendar event).
**Change Management**: Change Log Mode in Amazon Q Business enables incremental updates by capturing modifications made to content in Microsoft Teams. Instead of re-indexing all documents, it indexes only newly added, updated, or deleted items since the last crawl. Any changes to user or group access permissions are also recorded, ensuring accurate and up-to-date indexing.
**Failure handling**: The connector follows a fail-close approach, meaning if there are permission-related issues or API failures, affected documents are skipped from ingestion rather than being made publicly accessible. This prevents unauthorized access while maintaining data integrity.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
**Note**
Field mappings are available for the original Microsoft Teams connector only. The new connector uses automatic field mapping.
# Microsoft Teams data source connector field mappings
Field mappings
To help you structure data for retrieval and chat filtering, Amazon Q Business crawls data source document attributes or metadata and maps them to fields in your Amazon Q index.
Amazon Q has reserved fields that it uses when querying your application. When possible, Amazon Q automatically maps these built-in fields to attributes in your data source. If a built-in field doesn't have a default mapping, or if you want to map additional index fields, use the custom field mappings to specify how a data source attribute maps to your Amazon Q application. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Teams connector supports the following entities and the associated reserved and custom attributes.
**Note**
You can map any Teams field to the document title or document body Amazon Q reserved/default index fields.
**Topics**
+ [
## Chat messages
](#teams-field-mappings-chat-messages)
+ [
## Chat attachments
](#teams-field-mappings-chat-attachments)
+ [
## Channel posts
](#teams-field-mappings-channel-posts)
+ [
## Channel file attachments
](#teams-field-mappings-channel-file-attachments)
+ [
## Wiki
](#teams-field-mappings-wiki)
+ [
## Meeting chats
](#teams-field-mappings-meeting-chats)
+ [
## Meeting details
](#teams-field-mappings-meeting-details)
+ [
## Meeting notes
](#teams-field-mappings-meeting-notes)
+ [
## Meeting files
](#teams-field-mappings-meeting-files)
## Chat messages
| Microsoft Teams field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| subject | tms\$1subject | Custom | String |
| summary | tms\$1summary | Custom | String |
| importance | tms\$1importance | Custom | String |
| messageType | tms\$1message\$1type | Custom | String |
| sender | tms\$1sender | Custom | String |
| sourceUrl | \$1source\$1uri | Default | String |
| attachments | tms\$1attachments | Custom | String list |
| reactions | tms\$1reactions | Custom | String list |
| mentions | tms\$1mentions | Custom | String list |
| deletedAt | tms\$1last\$1deleted\$1at | Custom | Date |
| createdAt | \$1created\$1at | Default | Date |
| lastModifiedAt | \$1last\$1updated\$1at | Default | Date |
## Chat attachments
| Microsoft Teams field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| fileName | tms\$1name | Custom | String |
| size | tms\$1file\$1size | Custom | Long (numeric) |
| title | tms\$1title | Custom | String |
| sourceUrl | \$1source\$1uri | Default | String |
| lastModifiedBy | tms\$1last\$1modified\$1by | Custom | String |
| createdBy | tms\$1created\$1by | Custom | String |
| createdAt | \$1created\$1at | Default | Date |
| lastModifiedAt | \$1last\$1updated\$1at | Default | Date |
## Channel posts
| Microsoft Teams field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| subject | tms\$1subject | Custom | String |
| summary | tms\$1summary | Custom | String |
| importance | tms\$1importance | Custom | String |
| messageType | tms\$1message\$1type | Custom | String |
| createdBy | tms\$1created\$1by | Custom | String |
| deletedAt | tms\$1last\$1deleted\$1at | Custom | Date |
| sourceUrl | \$1source\$1uri | Default | String |
| mentions | tms\$1mentions | Custom | String list |
| reactions | tms\$1reactions | Custom | String list |
| attachments | tms\$1attachments | Custom | String list |
| createdAt | \$1created\$1at | Default | Date |
| lastModifiedAt | \$1last\$1updated\$1at | Default | Date |
## Channel file attachments
| Microsoft Teams field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| fileName | tms\$1name | Custom | String |
| size | tms\$1file\$1size | Custom | Long (numeric) |
| channelName | tms\$1channel\$1name | Custom | String |
| Title | tms\$1title | Custom | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdBy | tms\$1created\$1by | Custom | String |
| lastModifiedBy | tms\$1last\$1modified\$1by | Custom | String |
| createdAt | \$1created\$1at | Default | Date |
| lastModifiedAt | \$1last\$1updated\$1at | Default | Date |
| oneNoteDocument | tms\$1onenote\$1document | Custom | String |
| oneNoteSection | tms\$1onenote\$1section | Custom | String |
| oneNotePage | tms\$1onenote\$1page | Custom | String |
## Wiki
| Microsoft Teams field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| channelName | tms\$1channel\$1name | Custom | String |
| fileName | tms\$1name | Custom | String |
| size | tms\$1file\$1size | Custom | Long (numeric) |
| createdBy | tms\$1created\$1by | Custom | String |
| lastModifiedBy | tms\$1last\$1modified\$1by | Custom | String |
| title | tms\$1title | Custom | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| lastModifiedAt | \$1last\$1updated\$1at | Default | Date |
## Meeting chats
| Microsoft Teams field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| subject | tms\$1subject | Custom | String |
| summary | tms\$1summary | Custom | String |
| importance | tms\$1importance | Custom | String |
| messageType | tms\$1message\$1type | Custom | String |
| Sender | tms\$1sender | Custom | String |
| attachments | tms\$1attachments | Custom | String list |
| mentions | tms\$1mentions | Custom | String list |
| reactions | tms\$1reactions | Custom | String list |
| sourceUrl | \$1source\$1uri | Default | String |
| deletedAt | tms\$1last\$1deleted\$1at | Custom | Date |
| createdAt | \$1created\$1at | Default | Date |
| lastModifiedAt | \$1last\$1updated\$1at | Default | Date |
## Meeting details
| Microsoft Teams field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| subject | tms\$1subject | Custom | String |
| summary | tms\$1summary | Custom | String |
| importance | tms\$1importance | Custom | String |
| username | tms\$1from\$1user | Custom | String |
| eventStartTime | tms\$1event\$1start\$1time | Custom | Date |
| eventEndTime | tms\$1event\$1end\$1time | Custom | Date |
| sourceURL | \$1source\$1uri | Default | String |
## Meeting notes
| Microsoft Teams field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| fileName | tms\$1name | Custom | String |
| title | tms\$1title | Custom | String |
| createdBy | tms\$1created\$1by | Custom | String |
| lastModifiedBy | tms\$1last\$1modified\$1by | Custom | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| lastModifiedAt | \$1last\$1updated\$1at | Default | Date |
## Meeting files
| Microsoft Teams field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| fileName | tms\$1name | Custom | String |
| title | tms\$1title | Custom | String |
| size | tms\$1file\$1size | Custom | Long (numeric) |
| sourceUrl | \$1source\$1uri | Default | String |
| createdBy | tms\$1created\$1by | Custom | String |
| lastModifiedBy | tms\$1last\$1modified\$1by | Custom | String |
| createdAt | \$1created\$1at | Default | Date |
| lastModifiedAt | \$1last\$1updated\$1at | Default | Date |
# IAM role for Microsoft Teams connector
IAM role
**Note**
This section applies to both new and original Microsoft Teams connector versions.
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Troubleshooting your Microsoft Teams connector
Troubleshooting
The following table provides information about error codes you might see for the Microsoft Teams connector and suggested troubleshooting actions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| MST-5001 | Exception occurred while sending request to MSTeams api, please try again later. | Error related to authentication. Check logs for the specific error message. |
| MST-5101 | Exception occurred while validating configuration. | Error related to configurations. Check logs for the specific error message. |
| MST-5102 | ClientID cannot be null in Repository configuration. | Error related to configurations. Check logs for the specific error message. |
| MST-5103 | TenantId cannot be null in Repository configuration. | Error related to configurations. Check logs for the specific error message. |
| MST-5104 | ClientSecret cannot be null in Repository configuration | Error related to configurations. Check logs for the specific error message. |
| MST-5105 | Please add a valid paymentModel under additionalProperties. The paymentModel should be one of the following. | Error related to configurations. Check logs for the specific error message. |
| MST-5106 | Please add valid startCalendarDateTime & endCalendarDateTime under additionalProperties: startCalendarDateTime & endCalendarDateTime should be in this format 2016-12-01T00:00:00Z. | Error related to configurations. Please check logs for the specific error message. |
| MST-5107 | isCrawlChatMessage should be true or false. | Error related to configurations. Please check logs for the specific error message. |
| MST-5108 | isCrawlMeetingChatValue should be true or false. | Error related to configurations. Please check logs for the specific error message. |
| MST-5109 | isCrawlChatAttachment should be true or false. | Error related to configurations. Please check logs for the specific error message. |
| MST-5110 | isCrawlMeetingFile should be true or false. | Error related to configurations. Please check logs for the specific error message. |
| MST-5111 | isCrawlMeetingNote should be true or false. | Error related to configurations. Please check logs for the specific error message. |
| MST-5112 | isCrawlChannelPost should be true or false. | Error related to configurations. Please check logs for the specific error message. |
| MST-5113 | isCrawlChannelAttachment should be true or false | Error related to configurations. Please check logs for the specific error message. |
| MST-5114 | isCrawlChannelWiki should be true or false. | Error related to configurations. Please check logs for the specific error message. |
| MST-5115 | isCrawlCalendarMeeting should be true or false. | Error related to configurations. Please check logs for the specific error message. |
| MST-5116 | Invalid clientId pattern. | Error related to configurations. Please check logs for the specific error message.. |
| MST-5117 | ClientSecret Over maximum length. | Error related to configurations. Please check logs for the specific error message. |
| MST-5200 | Got exception from customer while accessing list of users. | Failure while fetching the list of users from Microsoft Graph API. Please check logs for more details. |
| MST-5201 | Got exception from customer while accessing list of chats. | Failure while fetching the list of chats from Microsoft Graph API. Please check logs for more details. |
| MST-5202 | Got exception from customer while accessing meeting chats. | Failure while fetching meeting chats from Microsoft Graph API. Please check logs for more details. |
| MST-5203 | Got exception from customer while accessing list of groups. | Failure while fetching the list of groups from Microsoft Graph API. Please check logs for more details. |
| MST-5204 | Got exception from customer while accessing list of channels. | Failure while fetching the list of channels from Microsoft Graph API. Please check logs for more details. |
| MST-5205 | Error occurred while fetching meeting events. | Failure while fetching meeting events from Microsoft Graph API. Please check logs for more details. |
| MST-5206 | Error occurred while fetching drive files. | Failure while fetching drive files from Microsoft Graph API. Please check logs for more details. |
| MST-5207 | Error while InterruptedException rate limit. | Failures while retrying API requests to fetch data from Microsoft Graph API. |
| MST-5209 | Got exception from customer while running full crawl. | Failures while running full crawl iterator. Please refer logs or contact connector team for more information. |
| MST-5210 | Exception occurred while accessing list of channel attachment from data source. | Failure while fetching the list of channels attachment from Microsoft Graph API. Please check logs for more details. |
| MST-5211 | Exception occurred while accessing meeting chat information for user. | Failure while accessing meeting chats from Microsoft Graph API. Please check logs for more details. |
| MST-5212 | Exception occurred while processing to access list of users. | Failure while processing to access list of users from Microsoft Graph API. Please check logs for more details. |
| MST-5213 | Exception occurred while processing to access list of groups. | Failure while processing to access list of groups from Microsoft Graph API. Please check logs for more details. |
| MST-5214 | Exception occurred while processing to access list of channel attachment. | Failure while processing to access list of channel attachment from Microsoft Graph API. Please check logs for more details. |
| MST-5215 | Exception occurred while processing to access meeting events. | Failure while processing to access meeting events from Microsoft Graph API. Please check logs for more details. |
| MST-5301 | Got exception from customer while running changelog. | Failures while handling changelog token. Please refer logs or contact connector team for more information. |
| MST-5302 | Error in serializing change log token. | Failures while serializing change log token. Please refer logs or contact connector team for more information. |
| MST-5303 | Error in de-serializing change log token. | Failures while de-serializing change log token. Please refer logs or contact connector team for more information. |
| MST-5400 | Exception occurred while running Identity Crawler. | Error occurred while fetching groups details from Microsoft Graph API. Please check logs for more details. |
| MST-5401 | Error while build groups details for Identity Crawler. | Failures while de-serializing change log token. Please refer logs or contact connector team for more information. |
| MST-5500 | Exception occurred while getting file content response. | Error occurred while fetching file content response details from Microsoft Graph API. Please check logs for more details. |
| MST-5501 | Only String, String List, Date and Long formats are supported for field mappings. | Error related to unsupported field mappings. Please check logs for the specific error message. |
| MST-5502 | IO Exception occurred. | IO Exception. |
# Connecting Amazon S3 to Amazon Q Business
Amazon S3
[Amazon Simple Storage Service](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) (Amazon S3) is an object storage service that stores data as objects within storage buckets. You can connect an Amazon S3 instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
After you integrate Amazon Q with Amazon S3, users can ask questions about the content stored in Amazon S3. For example, a user might ask about the main points discussed in a blog post on cloud security, the installation steps outlined in a user guide, findings from a case study on hybrid cloud usage, market trends noted in an analyst report, or key takeaways from a whitepaper on data encryption. This integration helps users to quickly find the specific information they need, improving their understanding and ability to make informed business decisions.
Amazon Q Business supports source attribution with citations. If you specify the `_source_uri` metadata field when you add metadata to your Amazon S3 bucket, the source attribution links returned by Amazon Q Business in the chat results will direct users to the configured URL. If you don't specify a `_source_uri`, users can still access the source documents through clickable citation links that will download the file at query time. This allows users to verify information even when no source URI is configured. To learn how to add metadata for your Amazon S3 connector, see [Adding document metadata in Amazon S3](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/s3-metadata.html).
**Note**
To learn how to create an Amazon S3 bucket, see [Creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) in the *Amazon Simple Storage Service User Guide*.
**Topics**
+ [
# Connecting Amazon S3 to Amazon Q Business using the New connector
](s3-v2-connector.md)
+ [
# Connecting Amazon S3 to Amazon Q Business (Old)
](s3-v1-connector.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon S3 to Amazon Q Business using the New connector
Amazon S3 (New)
**Note**
**Enhanced Version:** With the new connector, you can refresh your index significantly faster than before.
## Known limitations
The Amazon S3 connector has the following known limitations:
+ The [Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) bucket must be in the same AWS Region as your Amazon Q index, and your index must have permissions to access the bucket that contains your documents.
+ VPC connectivity not supported (use the old version if VPC support is required)
+ Custom field mappings not supported (use the old connector version if required)
+ Document enrichment is not supported. (use the old connector version if required)
# Overview
The following table gives an overview of the Amazon Q Business Amazon S3 connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/s3-v2-overview.html)
# Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Amazon S3, make sure you have:**
+ [Created an Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) and copied it's name.
**Note**
Your bucket must be in the same AWS Region as your Amazon Q index, and your index must have permissions to access the bucket that contains your documents.
# Using the console
The following procedure outlines how to connect Amazon Q Business to Amazon S3 using the AWS Management Console.
**Connecting Amazon Q to Amazon S3**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Amazon S3** data source to your Amazon Q application.
1. Then, on the **Amazon S3** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
IAM roles used for applications can't be used for data sources. If you are unsure if an existing role is used for an application, choose **Create a new role** to avoid errors.
1. **Data source location** – Choose the location of your Amazon S3 bucket:
1. **This account** – Selected by default. Choose this option if your Amazon S3 bucket is in the same account as your Amazon Q Business application.
1. **Other account** – Choose this option if your Amazon S3 bucket is in a different account.
1. **Account ID** – Specify the ID for the other account that owns the bucket.
1. **Sync scope**, enter the following information:
1. **Enter the data source location** – The path to the Amazon S3 bucket where your data is stored.
+ If you selected **This account**, you can select **Browse S3** to find and choose your bucket.
+ If you selected **Other account**, you must manually enter the bucket name as the browse option is not available for cross-account buckets.
**Note**
Your bucket must be in the same AWS Region as your Amazon Q Business index.
1. **Maximum file size - *optional*** – You can specify the file size limit in MB for Amazon Q crawling. Amazon Q crawls only files within the defined size limit. The default file size is 50MB. The maximum file size limit is 10 GB.
1. **Access control list configuration file location - *optional*** – The path to the location of a file containing a JSON structure that specifies access settings for the files stored in your S3 data source.
+ If you selected **This account**, you can select **Browse S3** to locate your ACL file.
+ If you selected **Other account**, you must manually enter the file path as the browse option is not available for cross-account buckets.
1. **Metadata files folder location - *optional*** – The path to the folder in which your metadata is stored.
+ If you selected **This account**, you can select **Browse S3** to locate your metadata folder.
+ If you selected **Other account**, you must manually enter the folder path as the browse option is not available for cross-account buckets.
1. **Filter patterns** – Add regex patterns to include or exclude documents from your index.
To include or exclude files and folders, you can use a prefix filter (for example `Data/`, where `Data` is a folder containing documents in your S3 bucket). You can also filter using glob patterns and file types.
1. **Multi-media content configuration – optional** – To enable content extraction from embedded images and visuals in documents, choose **Visual content in documents**. For more information, see [Extracting semantic meaning from embedded images and visuals](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/extracting-meaning-from-images.html).
To extract audio transcriptions and video content, enable **Audio Files**. To extract video content, enable **Video files**. For more information, see [Extracting semantic meaning from audio and video Content](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/Audio-video-extraction.html).
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Amazon S3 using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
**Topics**
+ [
## Amazon S3 configuration properties
](#s3-v2-configuration-keys)
+ [
## Amazon S3 JSON schema
](#s3-v2-api-json)
+ [
## Amazon S3 JSON schema example
](#s3-v2-api-json-example)
## Amazon S3 configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `type` | The type of data source. Specify `S3V2` as your data source type. | `string` The only allowed value is `S3V2`. | Yes |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has sub-properties: `bucketName` and `bucketOwnerAccountId`. | Yes |
| `bucketName` | The name of your Amazon S3 bucket. This is a sub-property for the `connectionConfiguration`. | `string` | Yes |
| `bucketOwnerAccountId` | The 12-digit AWS account ID that owns the S3 bucket. This is a sub-property for the `connectionConfiguration`. | `string` Must match pattern: `^\d{12}$` | Yes |
| `filterConfiguration` | Configuration for filtering which files to include or exclude from indexing. | `object` This property has sub-properties for patterns, prefixes, and file size limits. | No |
| `inclusionPatterns` | File patterns to include during indexing . This is a sub-property for the `filterConfiguration`. | `array` of `string` | No |
| `exclusionPatterns` | File patterns to exclude during indexing. This is a sub-property for the `filterConfiguration`. | `array` of `string` | No |
| `inclusionPrefixes` | S3 key prefixes to include during indexing (e.g., documents/, reports/). This is a sub-property for the `filterConfiguration`. | `array` of `string` | No |
| `exclusionPrefixes` | S3 key prefixes to exclude during indexing (e.g., temp/, cache/). This is a sub-property for the `filterConfiguration`. | `array` of `string` | No |
| `maxFileSizeInMegaBytes` | Maximum file size in megabytes to index. Files larger than this will be skipped. This is a sub-property for the `filterConfiguration`. | `number` Minimum: 0, Maximum: 10240 | No |
| `accessControlConfiguration` | Configuration for access control and permissions. | `object` This property has sub-properties for ACL configuration and default access type. | No |
| `aclConfigurationFilePath` | Path to the ACL configuration file in your S3 bucket. This is a sub-property for the `accessControlConfiguration`. | `string` Length: 1-1024 characters | No |
| `deletionProtectionConfiguration` | Configuration for deletion protection to prevent accidental bulk deletions. | `object` This property has sub-properties for enabling deletion protection and setting thresholds. | No |
| `enableDeletionProtection` | Whether to enable deletion protection. This is a sub-property for the `deletionProtectionConfiguration`. | `boolean` | No |
| `deletionProtectionThreshold` | Percentage threshold for deletion protection. If more than this percentage of documents would be deleted, the sync will be blocked. This is a sub-property for the `deletionProtectionConfiguration`. | `number` Default: 15 | No |
| `metadataFilesPrefix` | S3 key prefix where metadata files are stored for enhanced document processing. | `string` Length: 1-1024 characters | No |
## Amazon S3 JSON schema
The following is the Amazon S3 JSON schema with simplified configuration structure:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"pattern": "S3V2"
},
"connectionConfiguration": {
"type": "object",
"properties": {
"bucketName": {
"type": "string"
},
"bucketOwnerAccountId": {
"type": "string",
"pattern": "^\\d{12}$"
}
},
"required": ["bucketName", "bucketOwnerAccountId"]
},
"filterConfiguration": {
"type": "object",
"properties": {
"inclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionPrefixes": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionPrefixes": {
"type": "array",
"items": {
"type": "string"
}
},
"maxFileSizeInMegaBytes": {
"type": "number",
"minimum": 0,
"maximum": 10240
}
}
},
"accessControlConfiguration": {
"type": "object",
"properties": {
"aclConfigurationFilePath": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
}
},
"deletionProtectionConfiguration": {
"type": "object",
"properties": {
"enableDeletionProtection": {
"type": "boolean"
},
"deletionProtectionThreshold": {
"type": "number",
"default": 15
}
}
},
"metadataFilesPrefix": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
},
"required": [
"type",
"connectionConfiguration"
]
}
```
## Amazon S3 JSON schema example
The following is the Amazon S3 JSON schema example with simplified configuration:
```
{
"type": "S3V2",
"connectionConfiguration": {
"bucketName": "my-company-data-bucket",
"bucketOwnerAccountId": "123456789012"
},
"filterConfiguration": {
"inclusionPrefixes": ["documents/", "reports/"],
"exclusionPrefixes": ["temp/", "cache/"],
"maxFileSizeInMegaBytes": 100
},
"accessControlConfiguration": {
"aclConfigurationFilePath": "config/acl-config.json"
},
"deletionProtectionConfiguration": {
"enableDeletionProtection": true,
"deletionProtectionThreshold": 15
},
"metadataFilesPrefix": "metadata/"
}
```
# Connecting Amazon Q Business to Amazon S3 using AWS CloudFormation
Using AWS CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
**Topics**
+ [
## Amazon S3 configuration properties
](#s3-v2-configuration-keys)
+ [
## Amazon S3 JSON schema for using the configuration property with AWS CloudFormation
](#s3-v2-cfn-json)
+ [
## Amazon S3 YAML schema for using the configuration property with AWS CloudFormation
](#s3-v2-cfn-yaml)
## Amazon S3 configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `type` | The type of data source. Specify `S3V2` as your data source type. | `string` The only allowed value is `S3V2`. | Yes |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has sub-properties: `bucketName` and `bucketOwnerAccountId`. | Yes |
| `bucketName` | The name of your Amazon S3 bucket. This is a sub-property for the `connectionConfiguration`. | `string` | Yes |
| `bucketOwnerAccountId` | The 12-digit AWS account ID that owns the S3 bucket. This is a sub-property for the `connectionConfiguration`. | `string` Must match pattern: `^\d{12}$` | Yes |
| `filterConfiguration` | Configuration for filtering which files to include or exclude from indexing. | `object` This property has sub-properties for patterns, prefixes, and file size limits. | No |
| `inclusionPatterns` | File patterns to include during indexing . This is a sub-property for the `filterConfiguration`. | `array` of `string` | No |
| `exclusionPatterns` | File patterns to exclude during indexing. This is a sub-property for the `filterConfiguration`. | `array` of `string` | No |
| `inclusionPrefixes` | S3 key prefixes to include during indexing (e.g., documents/, reports/). This is a sub-property for the `filterConfiguration`. | `array` of `string` | No |
| `exclusionPrefixes` | S3 key prefixes to exclude during indexing (e.g., temp/, cache/). This is a sub-property for the `filterConfiguration`. | `array` of `string` | No |
| `maxFileSizeInMegaBytes` | Maximum file size in megabytes to index. Files larger than this will be skipped. This is a sub-property for the `filterConfiguration`. | `number` Minimum: 0, Maximum: 10240 | No |
| `accessControlConfiguration` | Configuration for access control and permissions. | `object` This property has sub-properties for ACL configuration and default access type. | No |
| `aclConfigurationFilePath` | Path to the ACL configuration file in your S3 bucket. This is a sub-property for the `accessControlConfiguration`. | `string` Length: 1-1024 characters | No |
| `deletionProtectionConfiguration` | Configuration for deletion protection to prevent accidental bulk deletions. | `object` This property has sub-properties for enabling deletion protection and setting thresholds. | No |
| `enableDeletionProtection` | Whether to enable deletion protection. This is a sub-property for the `deletionProtectionConfiguration`. | `boolean` | No |
| `deletionProtectionThreshold` | Percentage threshold for deletion protection. If more than this percentage of documents would be deleted, the sync will be blocked. This is a sub-property for the `deletionProtectionConfiguration`. | `number` Default: 15 | No |
| `metadataFilesPrefix` | S3 key prefix where metadata files are stored for enhanced document processing. | `string` Length: 1-1024 characters | No |
## Amazon S3 JSON schema for using the configuration property with AWS CloudFormation
Amazon S3 JSON schema
The following is the Amazon S3 JSON schema and examples for the configuration property for AWS CloudFormation.
**Topics**
+ [
### Amazon S3 JSON schema for using the configuration property with AWS CloudFormation
](#s3-v2-cfn-json-schema)
+ [
### Amazon S3 JSON schema example for using the configuration property with AWS CloudFormation
](#s3-v2-cfn-json-example)
### Amazon S3 JSON schema for using the configuration property with AWS CloudFormation
Amazon S3 JSON schema
The following is the Amazon S3 JSON schema for the configuration property for CloudFormation.
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"pattern": "S3V2"
},
"connectionConfiguration": {
"type": "object",
"properties": {
"bucketName": {
"type": "string"
},
"bucketOwnerAccountId": {
"type": "string",
"pattern": "^\\d{12}$"
}
},
"required": ["bucketName", "bucketOwnerAccountId"]
},
"filterConfiguration": {
"type": "object",
"properties": {
"inclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionPrefixes": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionPrefixes": {
"type": "array",
"items": {
"type": "string"
}
},
"maxFileSizeInMegaBytes": {
"type": "number",
"minimum": 0,
"maximum": 10240
}
}
},
"accessControlConfiguration": {
"type": "object",
"properties": {
"aclConfigurationFilePath": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
}
},
"deletionProtectionConfiguration": {
"type": "object",
"properties": {
"enableDeletionProtection": {
"type": "boolean"
},
"deletionProtectionThreshold": {
"type": "number",
"default": 15
}
}
},
"metadataFilesPrefix": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
},
"required": [
"type",
"connectionConfiguration"
]
}
```
### Amazon S3 JSON schema example for using the configuration property with AWS CloudFormation
Amazon S3 JSON schema example
The following is the Amazon S3 JSON example for the Configuration property for CloudFormation.
```
{
"type": "S3V2",
"connectionConfiguration": {
"bucketName": "my-company-data-bucket",
"bucketOwnerAccountId": "123456789012"
},
"filterConfiguration": {
"inclusionPatterns": ["*.pdf", "*.docx", "*.txt"],
"exclusionPatterns": ["*.tmp", "*.log"],
"inclusionPrefixes": ["documents/", "reports/"],
"exclusionPrefixes": ["temp/", "cache/"],
"maxFileSizeInMegaBytes": 100
},
"accessControlConfiguration": {
"aclConfigurationFilePath": "config/acl-config.json"
},
"deletionProtectionConfiguration": {
"enableDeletionProtection": true,
"deletionProtectionThreshold": 15
},
"metadataFilesPrefix": "metadata/"
}
```
## Amazon S3 YAML schema for using the configuration property with AWS CloudFormation
Amazon S3 YAML schema
The following is the Amazon S3 YAML schema and examples for the configuration property for AWS CloudFormation:
**Topics**
+ [
### Amazon S3 YAML schema example for using the configuration property with AWS CloudFormation
](#s3-v2-cfn-yaml-example)
### Amazon S3 YAML schema example for using the configuration property with AWS CloudFormation
Amazon S3 YAML schema example
The following is the Amazon S3 YAML example for the Configuration property for CloudFormation:
```
AWSTemplateFormatVersion: "2010-09-09"
Description: "CloudFormation Amazon S3 Data Source Template"
Resources:
DataSourceS3V2:
Type: "AWS::QBusiness::DataSource"
Properties:
ApplicationId: app12345-1234-1234-1234-123456789012
IndexId: indx1234-1234-1234-1234-123456789012
DisplayName: MyS3DataSourceV2
RoleArn: arn:aws:iam::123456789012:role/qbusiness-data-source-role
Configuration:
type: S3V2
connectionConfiguration:
bucketName: my-company-data-bucket
bucketOwnerAccountId: "123456789012"
filterConfiguration:
inclusionPatterns:
- "*.pdf"
- "*.docx"
- "*.txt"
exclusionPatterns:
- "*.tmp"
- "*.log"
inclusionPrefixes:
- "documents/"
- "reports/"
exclusionPrefixes:
- "temp/"
- "cache/"
maxFileSizeInMegaBytes: 100
accessControlConfiguration:
aclConfigurationFilePath: "config/acl-config.json"
deletionProtectionConfiguration:
enableDeletionProtection: true
deletionProtectionThreshold: 15
metadataFilesPrefix: "metadata/"
```
# IAM role
Whether you use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API, you must provide an IAM role that allows Amazon Q Business to access your Amazon S3 bucket.
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q Business resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role while creating your data source.
**Note**
To learn how to create an IAM role, see [Create a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html).
Cross-account Amazon S3 buckets are supported with Amazon Q Business. However, your bucket must be located in the same AWS Region as your Amazon Q Business index, and your index must have permissions to access the bucket containing your documents.
When you use an Amazon S3 bucket as a data source, you must provide a role that has permissions to:
+ Access your Amazon S3 bucket.
+ Permission to access the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchPutDocument.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchPutDocument.html) and [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchDeleteDocument.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchDeleteDocument.html) API operations in order to ingest documents.
+ Permission to access the Principal Store APIs needed to ingest access control and identity information from documents.
**To allow Amazon Q to use an Amazon S3 bucket as a data source, use the following role policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetObjectfromS3",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToListS3Buckets",
"Action": [
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::{{input_bucket_name}}"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "{{account_id}}"
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
},
{
"Sid": "AllowsAmazonQToCallPrincipalMappingAPIs",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToPassCustomerRole",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::{{account_id}}:role/QBusiness-DataSource-*"
],
"Condition": {
"StringEquals": {
"iam:PassedToService": "qbusiness.amazonaws.com"
}
}
}
]
}
```
**If the documents in the Amazon S3 bucket are encrypted, you must provide the following permissions to use the AWS KMS key to decrypt the documents:**
```
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
}
```
**To allow Amazon Q to assume a role, use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToAssumeRoleForServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
# Clickable URLs
Clickable Link Feature
The Clickable URL feature allows end users to access source documents through citation links in chat responses, regardless of whether a source URI is configured.
This feature improves the verification experience by making all documents of supported datasource types accessible. Currently, clickable links are only supported for Amazon S3, custom connectors, file upload and direct `BatchPutDocument` ingestion of documents.
**Configuration Requirements:** While this feature works automatically for new applications, existing customers may need additional configuration:
+ If you already use Amazon S3 data source for your Amazon Q Business application, you will need to perform a full sync of the data source for the clickable URLs feature to be available to your users.
+ If you already use an Amazon Q Business web experience, you may need to add additional permissions to the IAM role for the web experience. See the troubleshooting section below for details.
**Download Concurrency Limit:** For information about file size limits, see [Quotas and regions](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/quotas-regions.html).
**Access Control:** The Clickable URL respects all access control settings:
+ If a user's access to a file is revoked after they've viewed it in a chat, once a resync is performed subsequent attempts to access the file will be denied with a clear error message.
+ If a file is updated after a chat reference, then once a resync is performed clicking the link will retrieve the current version of the file.
+ If a file is deleted and a resync is performed users will receive a clear error message indicating the file no longer exists.
# Troubleshooting clickable links
Troubleshooting
This section helps you resolve errors that you might encounter when using clickable links for source references in your conversations with your Amazon Q Business AI assistant.
## Full sync required
**Note**
The following suggested troubleshooting steps apply only to existing accounts using the Amazon S3 connector.
**Issue**: When you try to access referenced URLs from an Amazon S3 or uploaded files data source, you receive the following error message.
**Error message**:
```
This document cannot be downloaded because the raw document download feature requires a full connector sync performed after 07/02/2025. Your admin has not yet completed this full sync. Please contact your admin to request a complete sync of the data source.
```
**Solution**: This error occurs when the data source hasn't completed a full sync after the clickable links feature was enabled. To resolve this issue:
+ For S3 data sources: Perform a full sync of the S3 data source.
+ For uploaded files data sources: Delete the files from the upload files data source and upload them again.
## Permission changes
**Issue**: When browsing conversation history, you click on a reference URL from an Amazon S3 data source but can't view or download the file.
**Error message**:
```
You no longer have permission to access this document. The access permissions for this document have been changed since you last accessed it. Please contact your admin if you believe you should have access to this content.
```
**Solution**: This error occurs when the permissions for the document in the ACLs on the Amazon S3 bucket changed after your conversation, removing your access to the file. The ACLs were updated in the Amazon Q Business index during a subsequent data source sync. If you believe you should have access to the document, contact your administrator to:
+ Review and update the ACLs
+ Perform a data source sync
## Document not found
**Issue**: When browsing conversation history, you click on a reference URL from an Amazon S3 or upload files data source but can't view or download the file.
**Error message**:
```
The document you're trying to access no longer exists in the data source. It may have been deleted or moved since it was last referenced. Please check with the admin if you need access to this document.
```
**Solution**: This error occurs when the document was deleted from the Amazon S3 bucket, moved to a different location, or deleted from the upload files data source after your conversation. The document was also removed from the Amazon Q Business index and staging bucket during a subsequent data source sync. If you believe the document shouldn't have been deleted, contact your administrator to restore the document and perform a data source sync.
## Insufficient permissions
**Note**
The following suggested troubleshooting steps apply only to existing accounts using the Amazon S3 connector.
**Issue**: When you click on a reference URL from an Amazon S3 or upload files data source, you can't view or download the file.
**Error message**:
```
Unable to download this document because your Web Experience lacks the required permissions. Your admin needs to update the IAM role for the Web Experience to include permissions for the GetDocumentContent API. Please contact your admin to request this IAM role update.
```
**Solution**: This error occurs when the web experience doesn't have the required permissions to invoke the GetDocumentContent API. Your administrator can resolve this error by updating the IAM role for the web experience with the permissions described in the *Considerations for using S3 clickable URLs* section.
If you already use a Amazon Q Business web experience, add the following permissions to the [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) for the Amazon Q Business web experience:
```
{
"Sid": "QBusinessGetDocumentContentPermission",
"Effect": "Allow",
"Action": ["qbusiness:GetDocumentContent"],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/*"
]
}
```
# Adding document metadata in Amazon S3
Adding metadata
To customize chat results for your end users, you can add metadata or document attributes to documents in an Amazon S3 bucket by using a metadata file. Metadata is additional information about a document, such as its title and the date and time it was created. To learn more about metadata in Amazon Q Business, see [Document attributes in Amazon Q Business](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
Amazon Q Business supports source attribution with citations. If you specify the `_source_uri` metadata field when you add metadata to your Amazon S3 bucket, the source attribution links returned by Amazon Q Business in the chat results will direct users to the configured URL. If you don't specify a `_source_uri`, users can still access the source documents through clickable citation links that will download the file at query time. This allows users to verify information even when no source URI is configured.
**Topics**
+ [
## Document metadata location
](#s3-metadata-location-v2)
+ [
## Document metadata structure
](#s3-metadata-structure-v2)
## Document metadata location
In Amazon S3, each metadata file can be associated with an indexed document. Your metadata files must be stored in the same Amazon S3 bucket as your indexed files. You can specify a location within the Amazon S3 bucket for your metadata files by using the AWS Management Console. Or, you can use the `metadataFilesPrefix` field of the Amazon S3 `configuration` parameter using the JSON schema when you create an Amazon S3 data source using the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API.
If you don't specify an Amazon S3 prefix, your metadata files must be stored in the same location as your indexed documents. If you specify an Amazon S3 prefix for your metadata files, they must be in a directory structure parallel to your indexed documents. Amazon Q looks only in the specified directory for your metadata. If the metadata isn't read, check that the directory location matches the location of your metadata.
The following examples show how the indexed document location maps to the metadata file location. The document's Amazon S3 key is appended to the metadata's Amazon S3 prefix and then suffixed with `.metadata.json` to form the metadata file's Amazon S3 path.
**Note**
The combined Amazon S3 key, the metadata's Amazon S3 prefix, and the `.metadata.json` suffix must be no more than a total of 1,024 characters. We recommend that your Amazon S3 key is less than 1,000 characters to account for additional characters when combining your key with the prefix and suffix.
```
Bucket name:
s3://bucketName
Document path:
documents
Metadata path:
none
File mapping
s3://bucketName/documents/file.txt ->
s3://bucketName/documents/file.txt.metadata.json
```
```
Bucket name:
s3://bucketName
Document path:
documents/legal
Metadata path:
metadata
File mapping
s3://bucketName/documents/legal/file.txt ->
s3://bucketName/metadata/documents/legal/file.txt.metadata.json
```
## Document metadata structure
You define your document metadata itself in a JSON file. The file must be a UTF-8 text file without a BOM marker. The file name of the JSON file must be `{
"authenticationUrl": "The OAUTH endpoint that Amazon Q connects to get an OAUTH token.",
"consumerKey": "The application public key generated when you created your Salesforce application.",
"consumerSecret": "The application private key generated when you created your Salesforce application.",
"password": "The password associated with the user logging in to the Salesforce instance.",
"securityToken": "The token associated with the user account logging in to the Salesforce instance.",
"username": "The user name of the user logging in to the Salesforce instance."
} |
| version | The version of this template that's currently supported. |
# How Amazon Q Business connector crawls Salesforce ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an Salesforce data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your Salesforce instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
You can apply ACL based chat filtering using Salesforce standard objects and chatter feeds. ACL based chat filtering isn't available for Salesforce knowledge articles.
**For standard objects, the `_user_id` and `_group_ids` are used as follows:**
+ `_user_id` – The username of the Salesforce user.
+ `_group_ids` – The group names in Salesforce.
+ Name of the Salesforce `Profile`
+ Name of the Salesforce `Group`
+ Name of the Salesforce `UserRole`
+ Name of the Salesforce `PermissionSet`
**For chatter feeds, the `_user_id` and `_group_ids` are used as follows:**
+ `_user_id` – The username of the Salesforce user. Only available if the item is posted in the user's feed.
+ `_group_ids` – Group IDs are used as follows. Only available if the feed item is posted in a chatter or collaboration group.
+ The name of the chatter or collaboration group.
+ If the group is public, `PUBLIC:ALL`.
**Important**
To maintain secure access control for Amazon Q Business, each user must have a unique email address across all connected data sources.
In Salesforce users can share an email address while having a different application-specific unique identifier. However, in Amazon Q Business email addresses act as unique identifiers.
This means that if a document is shared with a particular user (for example, arnav\$1desai@example.com who is part of pentesters@example.com) on the basis of an application-specific unique ID, every other user who shares pentesters@example.com (for example, xiulan\$1wang@example.com and efua\$1owusu@example.com, both of whom are part of pentesters@example.com) can receive Amazon Q Business responses with content from a document that was shared only with Arnav. Similarly, content created by Arnav that only he should be able to access via Amazon Q Business chat responses, could also be part of Amazon Q Business chat responses for Xiulan and Efua, because they share the same email address.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Salesforce Online data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Salesforce connector supports the following entities and the associated reserved and custom attributes.
**Note**
You can map any Salesforce field to the document title or document body Amazon Q reserved/default index fields.
**Topics**
+ [
## Account
](#salesforce-field-mappings-account)
+ [
## Campaign
](#salesforce-field-mappings-sc)
+ [
## Case
](#salesforce-field-mappings-case)
+ [
## Contact
](#salesforce-field-mappings-contact)
+ [
## Contract
](#salesforce-field-mappings-contract)
+ [
## Document
](#salesforce-field-mappings-document)
+ [
## Group
](#salesforce-field-mappings-group)
+ [
## Idea
](#salesforce-field-mappings-idea)
+ [
## Lead
](#salesforce-field-mappings-lead)
+ [
## Opportunity
](#salesforce-field-mappings-opportunity)
+ [
## Partner
](#salesforce-field-mappings-partner)
+ [
## Pricebook
](#salesforce-field-mappings-pricebook)
+ [
## Product
](#salesforce-field-mappings-product)
+ [
## Solution
](#salesforce-field-mappings-solution)
+ [
## Profile
](#salesforce-field-mappings-profile)
+ [
## Task
](#salesforce-field-mappings-task)
+ [
## User
](#salesforce-field-mappings-user)
+ [
## Chatter
](#salesforce-field-mappings-chatter)
+ [
## Knowledge articles
](#salesforce-field-mappings-ka)
+ [
## Attachments
](#salesforce-field-mappings-attachments)
+ [
## Custom object
](#salesforce-field-mappings-co)
## Account
Amazon Q supports crawling [Salesforce Online Accounts](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_account.htm) and offers the following account field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| authors | \$1authors | Default | String list |
| lastModifiedBy | sf\$1last\$1modified\$1by | Custom | String |
| shippingCity | sf\$1shipping\$1city | Custom | String |
| shippingCountry | sf\$1shipping\$1country | Custom | String |
| shippingState | sf\$1shipping\$1state | Custom | String |
| website | sf\$1website | Custom | String |
| industry | sf\$1industry | Custom | String |
| accountSource | sf\$1account\$1source | Custom | String |
| billingCity | sf\$1billing\$1city | Custom | String |
| billingCountry | sf\$1billing\$1country | Custom | String |
| billingState | sf\$1billing\$1state | Custom | String |
| createdBy | sf\$1created\$1by | Custom | String |
| lastActivityDate | sf\$1last\$1activity\$1date | Custom | Date |
| parentId | sf\$1parent\$1id | Custom | String |
| typeValue | sf\$1type\$1value | Custom | String |
| billingStreet | sf\$1billing\$1street | Custom | String |
| billingPostalCode | sf\$1billing\$1postal\$1code | Custom | String |
| billingLatitude | sf\$1billing\$1latitude | Custom | String |
| billingLongitude | sf\$1billing\$1longitude | Custom | String |
| billingGeocodeAccuracy | sf\$1billing\$1geocode\$1accuracy | Custom | String |
| shippingStreet | sf\$1shipping\$1street | Custom | String |
| shippingPostalCode | sf\$1shipping\$1postal\$1code | Custom | String |
| phone | sf\$1phone | Custom | String |
| fax | sf\$1fax | Custom | String |
| annualRevenue | sf\$1annual\$1revenue | Custom | String |
| numberOfEmployees | sf\$1number\$1of\$1employees | Custom | Long (numeric) |
| jigsaw | sf\$1jigsaw | Custom | String |
## Campaign
Amazon Q supports crawling [Salesforce Online Campaigns](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_campaign.htm) and offers the following campaign field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| isActive | sf\$1is\$1active | Custom | String |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| ownerName | \$1authors | Default | String list |
| lastModifiedBy | sf\$1last\$1modified\$1by | Custom | String |
| createdBy | sf\$1created\$1by | Custom | String |
| lastActivityDate | sf\$1last\$1activity\$1date | Custom | Date |
| parentId | sf\$1parent\$1id | Custom | String |
| campaignName | sf\$1campaign\$1name | Custom | String |
| status | sf\$1status | Custom | String |
| parentName | sf\$1parent\$1name | Custom | String |
| campaignType | sf\$1type | Custom | String |
| expectedRevenue | sf\$1expected\$1revenue | Custom | Long (numeric) |
| budgetedCost | sf\$1budgeted\$1cost | Custom | Long (numeric) |
| actualCost | sf\$1actual\$1cost | Custom | Long(numeric) |
| expectedResponse | sf\$1expected\$1response | Custom | String |
| numberSent | sf\$1number\$1sent | Default | Long numeric) |
| numberOfLeads | sf\$1number\$1of\$1leads | Custom | Long (numeric) |
| numberOfConvertedLeads | sf\$1number\$1of\$1convererted\$1leads | Custom | Long (numeric) |
| numberOfContacts | sf\$1number\$1of\$1contacts | Custom | Long (numeric) |
| numberOfResponses | sf\$1number\$1of\$1responses | Custom | Long (numeric) |
| numberOfOpportunites | sf\$1number\$1of\$1opportunities | Custom | Long (numeric) |
| numberOfWonOpportunities | sf\$1number\$1of\$1won\$1opportunitues | Custom | Long (numeric) |
| amountAllOpportunities | sf\$1amount\$1all\$1opportunities | Custom | Long (numeric) |
| amountWonOpportunities | sf\$1amount\$1won\$1opportunities | Custom | Long (numeric) |
## Case
Amazon Q supports crawling [Salesforce Online Cases](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_case.htm) and offers the following case field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| authors | \$1authors | Default | String list |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| ownerName | sf\$1owner\$1name | Custom | String |
| createdBy | sf\$1created\$1by | Custom | String |
| caseNumber | sf\$1case\$1number | Custom | String |
| isClosed | sf\$1is\$1closed | Custom | String |
| isEscalated | sf\$1is\$1escalated | Custom | String |
| priority | sf\$1priority | Custom | String |
| status | sf\$1status | Custom | String |
| accountName | sf\$1account\$1name | Custom | String |
| lastModifiedBy | af\$1last\$1modified\$1by | Custom | String |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| typeValue | sf\$1type | Custom | String |
| reason | sf\$1reason | Custom | String |
| contactId | sf\$1contact\$1id | Custom | String |
| origin | sf\$1origin | Custom | String |
| parentId | sf\$1parent\$1id | Custom | String |
| contactName | sf\$1contact\$1name | Custom | String |
| parentCaseNumber | sf\$1parent\$1case\$1number | Custom | String |
| parentSubject | sf\$1parent\$1subject | Custom | String |
| suppliedEmail | sf\$1supplied\$1email | Custom | String |
| contactPhone | sf\$1contact\$1phone | Custom | String |
| contactMobile | sf\$1contact\$1mobile | Custom | String |
| contactEmail | sf\$1contact\$1email | Custom | String |
| contactFax | sf\$1contact\$1fax | Custom | String |
| comments | sf\$1comments | Custom | String |
| lastViewedDate | sf\$1last\$1viewed\$1date | Custom | String |
## Contact
Amazon Q supports crawling [Salesforce Online Contacts](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_contact.htm) and offers the following contact field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| authors | \$1authors | Default | String list |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| lastModifiedBy | sf\$1last\$1modified\$1by | Custom | String |
| lastActivityDate | sf\$1last\$1activity\$1date | Custom | Date |
| createdBy | sf\$1created\$1by | Custom | String |
| contactName | sf\$1contact\$1name | Custom | String |
| phone | sf\$1phone | Custom | String |
| email | sf\$1email | Custom | String |
| department | sf\$1department | Custom | String |
| lastname | sf\$1lastname | Custom | String |
| title | sf\$1title | Custom | String |
| reportsTo | sf\$1reports\$1to | Custom | String |
| account | sf\$1account | Custom | String |
| otherStreet | sf\$1other\$1street | Custom | String |
| otherCity | sf\$1other\$1city | Custom | String |
| otherState | sf\$1other\$1state | Custom | String |
| otherPostalCode | sf\$1other\$1postal\$1code | Custom | String |
| otherCountry | sf\$1other\$1country | Custom | String |
| otherLatitude | sf\$1other\$1latitude | Custom | String |
| otherLongitude | sf\$1other\$1longitude | Custom | String |
| otherGeocodeAccuracy | sf\$1other\$1geocode\$1accuracy | Custom | String |
| mailingStreet | sf\$1mailing\$1street | Custom | String |
| mailingCity | sf\$1mailing\$1city | Custom | String |
| mailingState | sf\$1mailing\$1state | Custom | String |
| mailingPostalCode | sf\$1mailing\$1postal\$1code | Custom | String |
| mailingCountry | sf\$1mailing\$1country | Custom | String |
| mailingLatitude | sf\$1mailing\$1latitude | Custom | String |
| mailingLongitude | sf\$1mailing\$1longitude | Custom | String |
| mailingGeocodeAccuracy | sf\$1mailing\$1geocode\$1accuracy | Custom | String |
| fax | sf\$1fax | Custom | String |
| mobilePhone | sf\$1mobile\$1phone | Custom | String |
| homePhone | sf\$1home\$1phone | Custom | String |
| otherPhone | sf\$1other\$1phone | Custom | String |
| assistantPhone | sf\$1assistant\$1phone | Custom | String |
| assistantName | sf\$1assistant\$1name | Custom | String |
| leadSource | sf\$1lead\$1source | Custom | String |
| birthDate | sf\$1birthdate | Custom | Date |
| jigsaw | sf\$1jigsaw | Custom | String |
## Contract
Amazon Q supports crawling [Salesforce Online Contracts](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_contract.htm) and offers the following contract field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| authors | \$1authors | Default | String list |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| authors | \$1authors | Default | String list |
| accountId | \$1sf\$1accoung\$1id | Custom | String |
| ownerExpirationNotice | sf\$1owner\$1expiration\$1notice | Custom | String |
| billingStreet | sf\$1billing\$1street | Custom | String |
| billingCity | sf\$1billing\$1city | Custom | String |
| billingState | sf\$1billing\$1state | Custom | String |
| billingPostalCode | sf\$1billing\$1postal\$1code | Custom | String |
| billingCountry | sf\$1billing\$1country | Custom | String |
| contractTerm | sf\$1contract\$1term | Custom | String |
| ownerId | sf\$1owner\$1id | Custom | String |
| status | sf\$1status | Custom | String |
| customerSignedTitle | sf\$1customer\$1signed\$1title | Custom | String |
| specialTerms | sf\$1special\$1terms | Custom | String |
| statusCode | sf\$1status\$1code | Custom | String |
| contractNumber | sf\$1contract\$1number | Custom | String |
| lastViewedDate | sf\$1last\$1viewed\$1date | Custom | Date |
| lastReferenceDate | sf\$1last\$1reference\$1date | Custom | Date |
| billingAddressCity | sf\$1billing\$1address\$1city | Custom | String |
| billingAddressCountry | sf\$1billing\$1address\$1country | Custom | String |
| billingAddressPostalCode | sf\$1billing\$1address\$1postal\$1code | Custom | String |
| billingAddressState | sf\$1billing\$1address\$1state | Custom | String |
| billingAddressStreet | sf\$1billing\$1address\$1street | Custom | String |
| pricebookDescription | sf\$1pricebook\$1description | Custom | String |
| pricebookId | sf\$1pricebook\$1id | Custom | String |
| billingLatitude | sf\$1billing\$1latitude | Custom | String |
| billingLongitude | sf\$1billing\$1longitude | Custom | String |
| billingGeocodeAccuracy | sf\$1billing\$1geocode\$1accuracy | Custom | String |
| companySignedId | sf\$1company\$1signed\$1id | Custom | String |
| companySignedDate | sf\$1company\$1signed\$1date | Custom | Date |
| customerSignedId | sf\$1customer\$1signed\$1id | Custom | String |
| activatedById | sf\$1activated\$1by\$1id | Custom | String |
| activatedDate | sf\$1activated\$1date | Custom | Date |
| lastApprovedDate | sf\$1last\$1approved\$1date | Custom | Date |
| lastActivityDate | sf\$1last\$1activity\$1date | Custom | Date |
| accountName | sf\$1account\$1name | Custom | String |
| startDate | sf\$1start\$1date | Custom | Date |
| endDate | sf\$1end\$1date | Custom | Date |
| createdBy | sf\$1created\$1by | Custom | String |
## Document
Amazon Q supports crawling [Salesforce Online Documents](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_document.htm) and offers the following document field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| author | \$1authors | Default | String list |
| createdAt | \$1created\$1at | Default | Date |
| folder | sf\$1folder\$1name | Custom | String |
| isInternalUseOnly | sf\$1is\$1internal\$1use\$1only | Custom | String |
| isPublic | sf\$1is\$1public | Custom | String |
| keywords | sf\$1keywords | Custom | String |
| lastModifiedBy | sf\$1last\$1modified\$1by | Custom | String |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| fileName | sf\$1file\$1name | Custom | String |
| fileType | \$1file\$1type | Default | String |
| fileSize | sf\$1file\$1size | Custom | Long (numeric) |
| createdBy | sf\$1created\$1by | Custom | String |
| isBodySearchable | sf\$1is\$1body\$1searchable | Custom | String |
## Group
Amazon Q supports crawling [Salesforce Online Groups](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_group.htm) and offers the following group field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| groupEmail | sf\$1group\$1email | Custom | String |
| lastModifiedBy | sf\$1last\$1modified\$1by | Custom | String |
| lastModifiedDate | \$1last\$1modified\$1at | Default | Date |
| ownerId | sf\$1owner\$1id | Custom | String |
| groupName | sf\$1group\$1name | Custom | String |
| createdBy | \$1authors | Default | String list |
| lastFeedModifiedDate | sf\$1last\$1feed\$1modified\$1date | Custom | Date |
| hasPrivateFieldsAccess | sf\$1has\$1private\$1fields\$1access | Custom | String |
| canHaveGuests | sf\$1can\$1have\$1guests | Custom | String |
| isArchived | sf\$1is\$1archived | Custom | String |
| isAutoArchived | sf\$1is\$1auto\$1archive\$1disabled | Custom | String |
| memberCount | sf\$1member\$1count | Custom | String |
| collaborationType | sf\$1collabotration\$1type | Custom | String |
| informationTitle | sf\$1information\$1title | Custom | String |
## Idea
Amazon Q supports crawling [Salesforce Online Ideas](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_idea.htm) and offers the following idea field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| lastModifiedBy | sf\$1last\$1modified\$1by | Custom | String |
| title | sf\$1title | Custom | String |
| status | sf\$1status | Custom | String |
| createdByName | sf\$1created\$1by | Custom | String |
| parentIdea | sf\$1parent\$1idea\$1id | Custom | String |
| parentIdeaId | sf\$1parent\$1idea\$1id | Custom | String |
| lastModifiedDate | \$1last\$1modified\$1at | Default | Date |
| recordTypeId | sf\$1record\$1type\$1id | Custom | String |
| communityId | sf\$1community\$1id | Custom | String |
| numComments | sf\$1number\$1of\$1comments | Custom | Long (numeric) |
| voteScore | sf\$1vote\$1score | Custom | Long (numeric) |
| voteTotal | sf\$1vote\$1total | Custom | Long (numeric) |
| lastCommentDate | sf\$1last\$1comment\$1date | Custom | Date |
## Lead
Amazon Q supports crawling [Salesforce Online Leads](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_lead.htm) and offers the following lead field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| city | sf\$1city | Custom | String |
| company | sf\$1company | Custom | String |
| country | sf\$1country | Custom | String |
| createdAt | \$1created\$1at | Default | Date |
| lastModifiedBy | sf\$1last\$1modified\$1by | Custom | String |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| leadSource | sf\$1lead\$1source | Custom | String |
| state | sf\$1state | Custom | String |
| status | sf\$1status | Custom | String |
| convertedAccount | sf\$1converted\$1account | Custom | String |
| convertedAccountId | sf\$1converted\$1account\$1id | Custom | String |
| convertedContact | sf\$1converted\$1contact | Custom | String |
| convertedContactId | sf\$1converted\$1contact\$1id | Custom | String |
| convertedDate | sf\$1converted\$1date | Custom | Date |
| convertedOpportunity | sf\$1converted\$1opportunity | Custom | String |
| convertedOpportunityId | sf\$1converted\$1opportunity\$1id | Custom | String |
| firstName | sf\$1first\$1name | Custom | String |
| createdBy | \$1authors | Default | String list |
| isConverted | sf\$1is\$1converted | Custom | String |
| owner | sf\$1owner\$1name | Custom | String |
| lastActivityDate | sf\$1last\$1activity\$1date | Custom | Date |
| ownerId | sf\$1owner\$1id | Custom | String |
| lastName | sf\$1last\$1name | Custom | String |
| title | sf\$1title | Custom | String |
| street | sf\$1street | Custom | String |
| postalCode | sf\$1postal\$1code | Custom | String |
| latitude | sf\$1latitude | Custom | String |
| longitude | sf\$1longitude | Custom | String |
| geocodeAccuracy | sf\$1geocode\$1accuracy | Custom | String |
| phone | sf\$1phone | Custom | String |
| email | sf\$1email | Custom | String |
| industry | sf\$1industry | Custom | String |
| rating | sf\$1rating | Custom | String |
| annualRevenue | sf\$1annual\$1revenue | Custom | String |
| numberofEmployees | sf\$1number\$1of\$1employees | Custom | Long (numeric) |
| jigsaw | sf\$1jigsaw | Custom | String |
| jigsawContactId | sf\$1jigsaw\$1contact\$1id | Custom | String |
| emailBouncedReason | sf\$1email\$1bounced\$1reason | Custom | String |
| individualId | sf\$1individual\$1id | Custom | String |
## Opportunity
Amazon Q supports crawling [Salesforce Online Opportunities](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_opportunity.htm) and offers the following opportunity field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| accountName | sf\$1account\$1name | Custom | String |
| amount | sf\$1amount | Custom | String |
| campaign | sf\$1campaign\$1name | Custom | String |
| createdAt | \$1created\$1at | Default | Date |
| createdBy | sf\$1created\$1by | Custom | String |
| lastModifiedBy | sf\$1last\$1modified\$1by | Custom | String |
| lastModifiedDate | \$1last\$1updated\$1at | Default | Date |
| fiscalQuarter | sf\$1fiscal\$1quarter | Custom | String |
| fiscalYear | sf\$1fiscal\$1year | Custom | String |
| isClosed | sf\$1is\$1closed | Custom | String |
| isWon | sf\$1is\$1won | Custom | String |
| leadSource | sf\$1lead\$1source | Custom | String |
| opportunityName | sf\$1opportunity\$1name | Custom | String |
| accountId | sf\$1account\$1id | Custom | String |
| campaignId | sf\$1campaign\$1id | Custom | String |
| closeDate | sf\$1close\$1date | Custom | Date |
| typeValue | sf\$1type\$1value | Custom | String |
| lastActivityDate | sf\$1last\$1activity\$1date | Date | String |
| ownerName | sf\$1owner\$1name | Custom | String |
| ownerId | sf\$1owner\$1id | Custom | String |
| stageName | sf\$1stage\$1name | Custom | String |
| probability | sf\$1probability | Custom | Long (numeric) |
| nextStep | sf\$1next\$1step | Custom | String |
| forestCategory | sf\$1forecast\$1category | Custom | String |
| forestCategoryName | sf\$1forest\$1category\$1name | Custom | String |
| hasOpportunityLineItem | sf\$1has\$1opportunity\$1line\$1item | Custom | String |
| pricebook2id | sf\$1pricebook2\$1id | Custom | String |
| pushCount | sf\$1push\$1count | Custom | String |
| fiscal | sf\$1fiscal | Custom | String |
| contactId | sf\$1contact\$1id | Custom | String |
| lastViewedDate | sf\$1last\$1viewed\$1date | Custom | Date |
| hasOpenActivity | sf\$1has\$1open\$1activity | Custom | Long (numeric) |
| hasOverdueTask | sf\$1has\$1overdue\$1task | Custom | String |
## Partner
Amazon Q supports crawling [Salesforce Online Partner](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_partner.htm) and offers the following partner field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| createdBy | \$1authors | Default | String list |
| opportunityId | sf\$1opportunity\$1id | Custom | String |
| accountFromId | sf\$1account\$1from\$1id | Custom | String |
| accountToId | sf\$1role | Custom | String |
| role | sf\$1role | Custom | String |
| isPrimary | sf\$1is\$1primary | Custom | String |
| systemModstamp | sf\$1system\$1modstamp | Custom | Date |
| reversePartnerId | sf\$1reverse\$1partner\$1id | Custom | String |
| opportunity | sf\$1opportunity | Custom | String |
| accountFrom | sf\$1account\$1from | Custom | String |
| accountTo | sf\$1account\$1to | Custom | String |
## Pricebook
Amazon Q supports crawling [Salesforce Online Pricebooks](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_pricebook2.htm) and offers the following pricebook field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| isActive | sf\$1is\$1active | Custom | String |
| lastModifiedBy | sf\$1last\$1modified\$1by | Default | String |
| lastModifiedDate | \$1last\$1updated\$1at | Default | Date |
| pricebookName | sf\$1pricebook\$1name | Custom | String |
| createdAt | \$1created\$1at | Default | Date |
| createdBy | \$1authors | Default | String list |
| lastViewedDate | sf\$1last\$1viewed\$1date | Custom | Date |
| isStandard | sf\$1is\$1standard | Custom | String |
## Product
Amazon Q supports crawling [Salesforce Online Product](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_product2.htm) and offers the following product field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| family | sf\$1family | Custom | String |
| isActive | sf\$1is\$1active | Custom | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| lastModifiedBy | sf\$1last\$1modified\$1by | Custom | String |
| productCode | sf\$1product\$1code | Custom | String |
| createdBy | \$1authors | Default | String list |
| productName | sf\$1product\$1name | Custom | String |
| externalDataSourceId | sf\$1external\$1datasource\$1id | Custom | String |
| externalId | sf\$1external\$1id | Custom | String |
| displayUrl | sf\$1display\$1url | Custom | String |
| quantityUnitOfMeasure | sf\$1quantity\$1unit\$1of\$1measure | Custom | String |
| isArchived | sf\$1is\$1archived | Custom | String |
| lastViewedDate | sf\$1last\$1viewed\$1date | Custom | Date |
| stockKeepingUnit | sf\$1stock\$1keeping\$1unit | Custom | String |
## Solution
Amazon Q supports crawling [Salesforce Online Solutions](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_solution.htm) and offers the following solution field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| isPublished | sf\$1is\$1published | Custom | String |
| isReviewed | sf\$1is\$1reviewed | Custom | String |
| lastModifiedBy | sf\$1last\$1modified\$1by | Custom | String |
| lastModifiedDate | \$1last\$1updated\$1at | Default | Date |
| ownerName | sf\$1owner\$1name | Custom | String |
| solutionNumber | sf\$1solution\$1number | Custom | String |
| status | sf\$1status | Custom | String |
| timesUsed | sf\$1times\$1used | Custom | String |
| solutionName | sf\$1solution\$1name | Custom | String |
| createdByName | \$1authors | Default | String list |
| createdAt | \$1created\$1at | Default | Date |
| solutionNote | sf\$1solution\$1note | Custom | String |
| ownderId | sf\$1ownderId | Custom | String |
| lastViewedDate | sf\$1last\$1viewed\$1date | Custom | Date |
## Profile
Amazon Q supports crawling [Salesforce Online Profiles](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_profile.htm) and offers the following profile field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| lastModifiedBy | sf\$1last\$1modified\$1by | Custom | String |
| createdBy | \$1authors | Default | String list |
| createdAt | \$1created\$1at | Default | Date |
| userType | sf\$1user\$1type | Custom | String |
## Task
Amazon Q supports crawling [Salesforce Online Tasks](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_task.htm) and offers the following task field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| accountName | sf\$1account\$1name | Custom | String |
| lastModifiedBy | sf\$1last\$1modified\$1by | Custom | String |
| lastModifiedDate | \$1last\$1updated\$1at | Default | Date |
| ownerName | sf\$1owner\$1name | Custom | String |
| isRecurrence | sf\$1is\$1recurrence | Custom | String |
| isClosed | sf\$1is\$1closed | Custom | String |
| isArchived | sf\$1is\$1archived | Custom | String |
| priority | sf\$1priority | Custom | String |
| status | sf\$1status | Custom | String |
| whatId | sf\$1what\$1id | Custom | String |
| createdByName | \$1authors | Default | String list |
| createdAt | \$1created\$1at | Default | Date |
| subject | sf\$1subject | Custom | String |
| activityDate | sf\$1activity\$1date | Custom | Date |
| activityDate | sf\$1activity\$1date | Custom | Date |
| isHighPriority | sf\$1is\$1high\$1priority | Custom | String |
| ownerId | sf\$1owner\$1id | Custom | String |
| callType | sf\$1call\$1type | Custom | String |
## User
Amazon Q supports crawling [Salesforce Online Users](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_user.htm) and offers the following user field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| account | sf\$1account | Custom | String |
| isActive | sf\$1is\$1active | Custom | String |
| city | sf\$1city | Custom | String |
| lastModifiedBy | sf\$1last\$1modified\$1by | Custom | String |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| companyName | sf\$1company\$1name | Custom | String |
| country | sf\$1country | Custom | String |
| department | sf\$1department | Custom | String |
| division | sf\$1division | Custom | String |
| email | sf\$1email | Custom | String |
| employeeNumber | sf\$1employee\$1number | Custom | String |
| firstName | sf\$1first\$1name | Custom | String |
| lastName | sf\$1last\$1name | Custom | String |
| manager | sf\$1manager | Custom | String |
| state | sf\$1state | Custom | String |
| userRole | sf\$1user\$1role | Custom | String |
| username | sf\$1username | Custom | String |
| createdBy | \$1authors | Default | String list |
| createdAt | \$1created\$1at | Default | Date |
| street | sf\$1street | Custom | String |
| postalCode | sf\$1postal\$1code | Custom | String |
| latitude | sf\$1latitiude | Custom | String |
| longitude | sf\$1longitude | Custom | String |
| geocodeAccuracy | sf\$1geocode\$1accuracy | Custom | String |
| phone | sf\$1phone | Custom | String |
| fax | sf\$1fax | Custom | String |
| mobilePhone | sf\$1mobile\$1phone | Custom | String |
| profileName | sf\$1profile\$1name | Custom | String |
| aboutMe | sf\$1about\$1me | Custom | String |
| languageLocaleKey | sf\$1language\$1locale\$1key | Custom | String |
## Chatter
Amazon Q supports crawling [Salesforce Online Chatters](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_chatteractivity.htm) and offers the following chatter field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| body | sf\$1body | Custom | String |
| createdAt | \$1created\$1at | Default | Date |
| lastEditById | sf\$1last\$1edit\$1by\$1id | Custom | String |
| lastEditDate | sf\$1last\$1edit\$1date | Custom | Date |
| lastModifiedDate | \$1last\$1updated\$1at | Default | Date |
| insertedById | sf\$1inserted\$1by\$1id | Custom | String |
| createdBy | \$1authors | Default | String list |
| parentId | sf\$1parent\$1id | Custom | String |
| revision | sf\$1revision | Custom | String |
| status | sf\$1status | Custom | String |
| isRichText | sf\$1is\$1rich\$1texrt | Custom | String |
## Knowledge articles
Amazon Q supports crawling [Salesforce Online Knowledge articles](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_knowledgearticle.htm) and offers the following knowledge article field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| articleTitle | sf\$1title | Custom | String |
| articleNumber | sf\$1article\$1number | Default | Date |
| knowledgeArticleId | sf\$1knowledge\$1article\$1id | Custom | String |
| lastPublishedDate | sf\$1last\$1published\$1date | Custom | Date |
| publishStatus | sf\$1publish\$1status | Custom | String |
| versionNumber | sf\$1version\$1number | Custom | String |
| language | sf\$1language | Custom | String |
| ownerId | sf\$1ownder\$1id | Custom | String |
| summary | sf\$1summary | Custom | String |
| firstPublishedDate | sf\$1first\$1published\$1date | Custom | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| archivedDate | sf\$1archived\$1date | Custom | Date |
| isLatestVersion | sf\$1is\$1latest\$1version | Custom | String |
| sourceId | sf\$1sourceId | Custom | String |
| createdBy | \$1authors | Default | String list |
| assignmentDate | sf\$1assignment\$1date | Custom | Long (numeric) |
| assignmentDueDate | sf\$1assignment\$1due\$1date | Custom | Date |
| articleCaseAttachCount | sf\$1article\$1case\$1attach\$1count | Custom | Long (numeric) |
| articleTotalViewCount | sf\$1article\$1total\$1view\$1count | Custom | Long (numeric) |
| urlName | sf\$1url\$1name | Custom | String |
| assignmentNote | sf\$1assignment\$1date | Custom | String |
| migratedToFromArticleVersion | sf\$1migrated\$1article\$1version | Custom | String |
| assignedBy | sf\$1assigned\$1by | Custom | String |
| assignedTo | sf\$1assigned\$1to | Custom | Date |
## Attachments
Amazon Q supports crawling [Salesforce Online Attachments](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_attachment.htm) and offers the following attachment field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| fileName | sf\$1file\$1name | Custom | String |
| fileType | \$1file\$1type | Default | String |
| fileSize | sf\$1file\$1size | Custom | Long (numeric) |
| parentName | sf\$1parent\$1name | Default | String |
| createdBy | \$1authors | Default | String list |
## Custom object
Amazon Q supports crawling custom objects and offers the following custom object field mappings.
| Salesforce field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| lastModifiedById | sf\$1last\$1modified\$1by\$1id | Custom | String |
| customObjectName | sf\$1custom\$1object\$1name | Custom | String |
| createdBy | \$1authors | Default | String list |
| lastModifiedBy | sf\$1last\$1modified\$1by | Custom | String |
| documentbody | \$1document\$1body | Custom | String |
# IAM role for Salesforce Online connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Troubleshooting your Salesforce Online connector
Error Codes
The following table provides information about error codes you may see for the Salesforce Online connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| SF-5001 | Invalid HostURL. | Provide valid HostURL. |
| SF-5002 | Invalid userName or password. | Provide valid userName or password. |
| SF-5003 | Invalid clientSecret. | Provide valid clientSecret. |
| SF-5004 | Invalid clientId. | Provide valid clientId. |
| SF-5005 | Invalid grant type. | Provide valid grant type. |
| SF-5006 | Error while generating Access Token. | Provide valid credentials or try again later. |
| SF-5100 | Null/empty HostUrl. | Provide HostUrl. |
| SF-5101 | Null/empty client ID. | Provide client ID. |
| SF-5102 | Null/empty client secret | Provide client secret. |
| SF-5103 | Null/empty username. | Provide username. |
| SF-5104 | Null/empty password. | Provide password. |
| SF-5150 | Null/empty authentication URL. | Provide authentication URL. |
| SF-5151 | Invalid HostURL pattern. | Provide valid HostURL pattern. |
| SF-5152 | Invalid Authentication URL. | Provide valid Authentication URL. |
| SF-5500 | ContinuableInternalServerError. | Try again later. |
# Connecting ServiceNow Online to Amazon Q Business
ServiceNow Online
ServiceNow provides a cloud-based service management system to create and manage organization-level workflows, such as IT services, ticketing systems, and support. You can connect ServiceNow Online instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# Known limitations for the Amazon Q Business ServiceNow Online connector
](servicenow-limitations.md)
+ [
# ServiceNow Online connector overview
](servicenow-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to ServiceNow Online
](servicenow-prereqs.md)
+ [
# Connecting Amazon Q Business to ServiceNow Online using the console
](servicenow-console.md)
+ [
# Connecting Amazon Q Business to ServiceNow using APIs
](servicenow-api.md)
+ [
# Connecting Amazon Q Business to ServiceNow using AWS CloudFormation
](servicenow-cfn.md)
+ [
# How Amazon Q Business connector crawls ServiceNow ACLs
](servicenow-user-management.md)
+ [
# ServiceNow Online data source connector field mappings
](servicenow-field-mappings.md)
+ [
# IAM role for Amazon Q Business ServiceNow Online connector
](servicenow-iam-role.md)
+ [
# Understand error codes in the Amazon Q Business ServiceNow Online connector
](servicenow-error-codes.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Amazon Q Business ServiceNow Online connector
Known limitations
The ServiceNow Online connector has the following known limitations:
+ There is no REST API to wake up your ServiceNow instance. To activate it when it's in hibernation mode, log in to the your ServiceNow instance.
+ Because Amazon Q Business uses email address as unique identifiers, each user must have a unique email address.
+ We don't support ServiceNow access controls.
+ We don't support ServiceNow user criteria.
+ Only the following ServiceNow roles are supported for incidents:
+ ITIL: This role provides broad access to incident management functionality.
+ Custom roles: You can create custom roles with specific incident access permissions.
# ServiceNow Online connector overview
Overview
The following table gives an overview of the Amazon Q Business ServiceNow Online connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-overview.html)
# Prerequisites for connecting Amazon Q Business to ServiceNow Online
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In ServiceNow, make sure you have:**
+ Created a Personal or Enterprise Developer Instance and have a ServiceNow instance with an administrative role.
+ Copied the host of your ServiceNow instance URL. The format for the host URL you enter is *your-domain.service-now.com*. You need your ServiceNow instance URL to connect to Amazon Q.
+ Configured basic authentication credentials containing a username and password to allow Amazon Q to connect to your ServiceNow instance.
+ **Optional:** Configured an OAuth 2.0 credential token that can identify Amazon Q using a username, password, and a generated client ID, and a client secret. For more information, see [ServiceNow documentation on OAuth 2.0 authentication](https://www.servicenow.com/docs/bundle/utah-platform-security/page/integrate/single-sign-on/concept/c_Authentication.html) on the ServiceNow website.
+ Depending on what you are searching for, you will need specific roles. Note that if you are searching through public articles, you don't require any specific role. Apply the following roles depending on your use case:
+ When searching Knowledge article documents in Amazon Q, the user should have any of the following roles - Knowledge, Knowledge\$1Admin, and User\$1Admin or Itil.
+ When searching Service Catalog documents in Amazon Q, the user should have a catalog role.
+ When searching the Incident document in Amazon Q, the user should have the incident\$1manager role.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your ServiceNow Online authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
**Note**
For more information on connecting ServiceNow Online to Amazon Q Business, see [Derive generative AI-powered insights from ServiceNow with Amazon Q Business](https://aws.amazon.com/blogs/machine-learning/derive-generative-ai-powered-insights-from-servicenow-with-amazon-q-business/) in the *AWS Machine Learning Blog*.
# Connecting Amazon Q Business to ServiceNow Online using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to ServiceNow Online using the AWS Management Console.
**Connecting Amazon Q to ServiceNow Online**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **ServiceNow Online** data source to your Amazon Q application.
1. Then, on the **ServiceNow Online** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, enter the following information:
+ ** ServiceNow host** – Enter your ServiceNow host name without the protocol. For example, *example.service-now.com*.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. **Authentication** – Choose between **Basic authentication** and **OAuth 2.0 authentication** and then enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. Basic Authentication – Enter the **Secret name**, **Username**, and **Password** for your ServiceNow account.
If using OAuth2 Authentication – Enter the **Secret name**, **Username**, **Password**, **Client ID**, and **Client Secret** that you created in your ServiceNow account.
1. Choose **Save and add secret**.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-connector.html#servicenow-iam).
1. **Sync scope** – Set the content that you want to sync.
1. For **Knowledge articles**, choose from the following options :
+ **Knowledge articles** – Choose to index knowledge articles.
+ **Knowledge article attachments** – Choose to index knowledge article attachments.
+ **Type of knowledge articles** – Choose between **Only public articles** and **Knowledge articles based on ServiceNow filter query**, based on your use case. If you select **Include articles based on ServiceNow filter query**, you must enter a **Filter query** copied from your ServiceNow account. Example filter queries include: *workflow\$1state=draft^EQ*, *kb\$1knowledge\$1base=dfc19531bf2021003f07e2c1ac0739ab^text ISNOTEMPTY^EQ*, and *article\$1type=text^active=true^EQ*.
**Important**
If you choose to crawl **Only public articles**, Amazon Q crawls only knowledge articles assigned a public access role in ServiceNow Online.
+ **Include articles based on short description filter** – Specify regular expression patterns to include or exclude specific articles. For example, use `.*article[1,2].*` to include articles containing `article1` or `article2.` in their short descriptions. Use `(^mystart.*|.*endwith$)` to crawl articles with short descriptions starting with `mystart` or ending with `endwith`.
1. For **Service catalog items**:
+ **Service catalog items** – Choose to index service catalog items.
+ **Service catalog item attachments** – Choose to index service catalog item attachments.
+ **Active service catalog items** – Choose to index active service catalog items.
+ **Inactive service catalog items** – Choose to index inactive service catalog items.
+ **Filter query** – Choose to include service catalog items based on a filter defined in your ServiceNow instance. Example filter queries include: *short\$1descriptionLIKEAccess^category=2809952237b1300054b6a3549dbe5dd4^EQ*, *nameSTARTSWITHService^active=true^EQ*.
+ **Include service catalog items based on short description filter** – Specify a regex pattern to include specific catalog items.
1. For **Incidents**:
+ **Incidents** – Choose to index service incidents.
+ **Incident attachments** – Choose to index incident attachments.
+ **Active incidents** – Choose to index active incidents.
+ **Inactive incidents** – Choose to index inactive incidents.
+ **Active incident type** – Choose between **All incidents**, **Open incidents**, **Open - unassigned incidents**, and **Resolved incidents**, depending on your use case.
+ **Filter query** – Choose to include incidents based on a filter defined in your ServiceNow instance. Example filter queries include: *short\$1descriptionLIKETest^urgency=3^state=1^EQ*, and *priority=2^category=software^EQ *.
+ **Include incidents based on short description filter** – Specify a regex pattern to include specific incidents.
1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB.
1. In **Additional configuration – *optional***:
+ **Attachment regex patterns** – Add regular expression patterns to include or exclude specific attached files of catalogs, knowledge articles, and incidents. You can add up to 100 patterns.
1. **Multi-media content configuration – optional** – To enable content extraction from embedded images and visuals in documents, choose **Visual content in documents**.
To extract audio transcriptions and video content, enable processing for the following file types:
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. For **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync** – Sync all content regardless of the previous sync status.
+ **New, modified, or deleted content sync** – Only sync new, modified, and deleted content.
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to ServiceNow using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
**Topics**
+ [
## ServiceNow configuration properties
](#servicenow-configuration-keys)
+ [
## ServiceNow JSON schema
](#servicenow-json)
+ [
## ServiceNow JSON schema example
](#s3-api-json-example)
## ServiceNow configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has the following sub-property: `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-property: `hostUrl`, `authType`. | Yes |
| `hostUrl` | The ServiceNow host URL. For example, your-domain.service-now.com. | `string` | Yes |
| `authType` | The type of authentication you are using, either basicAuth or OAuth2. | `string` | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-api.html) | A list of ServiceNow objects that Amazon Q crawls and maps the attributes of to Amazon Q index field names. | `object` This property has the following sub-properties: `indexFieldName`, `indexFieldType`, `dataSourceFieldName`, and `dateFieldFormat`. | Yes |
| `indexFieldName` | The field name of your ServiceNow pages and assets. | `string` | Yes |
| `indexFieldType` | The field type of your ServiceNow pages and assets. | `string` The allowed values are `STRING`, `STRING_LIST`, `DATE`, and `LONG`. | Yes |
| `dataSourceFieldName` | The data source field name of your ServiceNow pages and assets. | `string` | Yes |
| `dateFieldFormat` | The date format of your ServiceNow pages and assets. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-api.html) | Yes |
| `maxFileSizeInMegaBytes` | Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-api.html) | Specify specific knowledge articles, incident queries, and service catalog queries to crawl. | `string` | No |
| `incidentStateType` | Specify incidents to crawl by state type: whether Open, Open - Unassigned, Resolved, or All. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-api.html) | A list of regular expression patterns to include and exclude specific files in your ServiceNow data source. Files that match the patterns are included in the index. Files that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence and the file isn't included in the index. | `string` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-api.html) | A list of regular expression patterns to exclude specific content in your ServiceNow data source. Content that matches the patterns are excluded from the index. Content that doesn't match the patterns are included in the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-api.html) | A list of regular expression patterns to include specific content in your ServiceNow data source. Content that matches the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-api.html) | Specify true to index ServiceNow knowledge articles, service catalogs, incidents, and attachments and their ACLs. | `boolean` | No |
| `type` | The type of data source. We recommend that you use SERVICENOWV2 as your data source type. | `string` Valid values are `SERVICENOWV2` and `SERVICENOW`. | Yes |
| `enableIdentityCrawler` | `true` to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). | `boolean` | No |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-api.html) | Yes |
| `secretARN` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your ServiceNow. | `string` The secret must contain a JSON structure with the following keys: {
"username": "user name",
"password": "password"
} If you use OAuth2 authentication, your secret must contain a JSON structure with the following keys: {
"username": "user name",
"password": "password",
"clientId": "client id",
"clientSecret": "client secret"
} | Yes |
| `version` | The version of the template that's currently supported. | `string` | No |
## ServiceNow JSON schema
The following is the ServiceNow JSON schema:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["SERVICENOWV2", "SERVICENOW"]
},
"syncMode": {
"type": "string",
"enum": ["FORCED_FULL_CRAWL", "FULL_CRAWL"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"hostUrl": {
"type": "string",
"pattern": "^(?!(^(https?|ftp|file):\\/\\/))[a-z0-9-]+(.service-now.com|.servicenowservices.com)$",
"minLength": 1,
"maxLength": 2048
},
"authType": {
"type": "string",
"enum": ["basicAuth", "OAuth2"]
},
"servicenowInstanceVersion": {
"type": "string",
"enum": ["Tokyo", "Sandiego", "Rome", "Vancouver", "Others"]
}
},
"required": ["hostUrl", "authType", "servicenowInstanceVersion"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"knowledgeArticle": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "STRING_LIST"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "LONG", "DATE", "STRING_LIST"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"serviceCatalog": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "STRING_LIST"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"incident": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "STRING_LIST"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"maxFileSizeInMegaBytes": {
"type": "string"
},
"isCrawlKnowledgeArticle": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlKnowledgeArticleAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"includePublicArticlesOnly": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"knowledgeArticleFilter": {
"type": "string"
},
"incidentQueryFilter": {
"type": "string"
},
"serviceCatalogQueryFilter": {
"type": "string"
},
"isCrawlServiceCatalog": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlServiceCatalogAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlActiveServiceCatalog": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlInactiveServiceCatalog": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlIncident": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlIncidentAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlActiveIncident": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlInactiveIncident": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"applyACLForKnowledgeArticle": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"applyACLForServiceCatalog": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"applyACLForIncident": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"incidentStateType": {
"type": "array",
"items": {
"type": "string",
"enum": ["Open", "Open - Unassigned", "Resolved", "All"]
}
},
"knowledgeArticleTitleRegExp": {
"type": "string"
},
"serviceCatalogTitleRegExp": {
"type": "string"
},
"incidentTitleRegExp": {
"type": "string"
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"type",
"syncMode",
"secretArn",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
}
```
## ServiceNow JSON schema example
The following is the ServiceNow JSON schema example:
```
{
"type": "SERVICENOWV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-servicenow-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"hostUrl": "mycompany.service-now.com",
"authType": "basicAuth",
"servicenowInstanceVersion": "Tokyo"
}
},
"repositoryConfigurations": {
"knowledgeArticle": {
"fieldMappings": [
{
"indexFieldName": "article_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"serviceCatalog": {
"fieldMappings": [
{
"indexFieldName": "catalog_item_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"incident": {
"fieldMappings": [
{
"indexFieldName": "incident_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"maxFileSizeInMegaBytes": "50",
"isCrawlKnowledgeArticle": "true",
"isCrawlKnowledgeArticleAttachment": "true",
"includePublicArticlesOnly": "false",
"knowledgeArticleFilter": "filter_condition",
"incidentQueryFilter": "incident_condition",
"serviceCatalogQueryFilter": "service_catalog_condition",
"isCrawlServiceCatalog": "true",
"isCrawlServiceCatalogAttachment": "true",
"isCrawlActiveServiceCatalog": "true",
"isCrawlInactiveServiceCatalog": "false",
"isCrawlIncident": "true",
"isCrawlIncidentAttachment": "false",
"isCrawlActiveIncident": "true",
"isCrawlInactiveIncident": "false",
"applyACLForKnowledgeArticle": "true",
"applyACLForServiceCatalog": "true",
"applyACLForIncident": "true",
"incidentStateType": ["Open", "Resolved"],
"knowledgeArticleTitleRegExp": ".*",
"serviceCatalogTitleRegExp": ".*",
"incidentTitleRegExp": ".*",
"inclusionFileTypePatterns": ["*.pdf", "*.docx"],
"exclusionFileTypePatterns": ["*.tmp"],
"inclusionFileNamePatterns": ["important-*"],
"exclusionFileNamePatterns": ["temporary-*"],
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
```
# Connecting Amazon Q Business to ServiceNow using AWS CloudFormation
Using the CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
**Topics**
+ [
## ServiceNow configuration properties
](#servicenow-configuration-keys)
+ [
## ServiceNow JSON schema for using the configuration property with AWS CloudFormation
](#servicenow-cfn-json)
+ [
## ServiceNow YAML schema for using the configuration property with AWS CloudFormation
](#servicenow-cfn-yaml)
## ServiceNow configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has the following sub-property: `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-property: `hostUrl`, `authType`. | Yes |
| `hostUrl` | The ServiceNow host URL. For example, your-domain.service-now.com. | `string` | Yes |
| `authType` | The type of authentication you are using, either basicAuth or OAuth2. | `string` | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-cfn.html) | A list of ServiceNow objects that Amazon Q crawls and maps the attributes of to Amazon Q index field names. | `object` This property has the following sub-properties: `indexFieldName`, `indexFieldType`, `dataSourceFieldName`, and `dateFieldFormat`. | Yes |
| `indexFieldName` | The field name of your ServiceNow pages and assets. | `string` | Yes |
| `indexFieldType` | The field type of your ServiceNow pages and assets. | `string` The allowed values are `STRING`, `STRING_LIST`, `DATE`, and `LONG`. | Yes |
| `dataSourceFieldName` | The data source field name of your ServiceNow pages and assets. | `string` | Yes |
| `dateFieldFormat` | The date format of your ServiceNow pages and assets. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-cfn.html) | Yes |
| `maxFileSizeInMegaBytes` | Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-cfn.html) | Specify specific knowledge articles, incident queries, and service catalog queries to crawl. | `string` | No |
| `incidentStateType` | Specify incidents to crawl by state type: whether Open, Open - Unassigned, Resolved, or All. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-cfn.html) | A list of regular expression patterns to include and exclude specific files in your ServiceNow data source. Files that match the patterns are included in the index. Files that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence and the file isn't included in the index. | `string` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-cfn.html) | A list of regular expression patterns to exclude specific content in your ServiceNow data source. Content that matches the patterns are excluded from the index. Content that doesn't match the patterns are included in the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-cfn.html) | A list of regular expression patterns to include specific content in your ServiceNow data source. Content that matches the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array (string)` | No |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-cfn.html) | Specify true to index ServiceNow knowledge articles, service catalogs, incidents, and attachments and their ACLs. | `boolean` | No |
| `type` | The type of data source. We recommend that you use SERVICENOWV2 as your data source type. | `string` Valid values are `SERVICENOWV2` and `SERVICENOW`. | Yes |
| `enableIdentityCrawler` | `true` to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to specific documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). | `boolean` | No |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/servicenow-cfn.html) | Yes |
| `secretARN` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your ServiceNow. | `string` The secret must contain a JSON structure with the following keys: {
"username": "user name",
"password": "password"
} If you use OAuth2 authentication, your secret must contain a JSON structure with the following keys: {
"username": "user name",
"password": "password",
"clientId": "client id",
"clientSecret": "client secret"
} | Yes |
| `version` | The version of the template that's currently supported. | `string` | No |
## ServiceNow JSON schema for using the configuration property with AWS CloudFormation
ServiceNow JSON schema
The following is the ServiceNow JSON schema and examples for the configuration property for AWS CloudFormation.
**Topics**
+ [
### ServiceNow JSON schema for using the configuration property with AWS CloudFormation
](#servicenow-cfn-json-schema)
+ [
### ServiceNow JSON schema example for using the configuration property with AWS CloudFormation
](#servicenow-cfn-json-example)
### ServiceNow JSON schema for using the configuration property with AWS CloudFormation
ServiceNow JSON schema
The following is the ServiceNow JSON schema for the configuration property for CloudFormation
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["SERVICENOWV2", "SERVICENOW"]
},
"syncMode": {
"type": "string",
"enum": ["FORCED_FULL_CRAWL", "FULL_CRAWL"]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"hostUrl": {
"type": "string",
"pattern": "^(?!(^(https?|ftp|file):\\/\\/))[a-z0-9-]+(.service-now.com|.servicenowservices.com)$",
"minLength": 1,
"maxLength": 2048
},
"authType": {
"type": "string",
"enum": ["basicAuth", "OAuth2"]
}
},
"required": ["hostUrl", "authType"]
}
},
"required": ["repositoryEndpointMetadata"]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"knowledgeArticle": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "STRING_LIST"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"attachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "LONG", "DATE", "STRING_LIST"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"serviceCatalog": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "STRING_LIST"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
},
"incident": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "DATE", "STRING_LIST"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"maxFileSizeInMegaBytes": {
"type": "string"
},
"isCrawlKnowledgeArticle": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlKnowledgeArticleAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"includePublicArticlesOnly": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"knowledgeArticleFilter": {
"type": "string"
},
"incidentQueryFilter": {
"type": "string"
},
"serviceCatalogQueryFilter": {
"type": "string"
},
"isCrawlServiceCatalog": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlServiceCatalogAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlActiveServiceCatalog": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlInactiveServiceCatalog": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlIncident": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlIncidentAttachment": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlActiveIncident": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"isCrawlInactiveIncident": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"applyACLForKnowledgeArticle": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"applyACLForServiceCatalog": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"applyACLForIncident": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"incidentStateType": {
"type": "array",
"items": {
"type": "string",
"enum": ["Open", "Open - Unassigned", "Resolved", "All"]
}
},
"knowledgeArticleTitleRegExp": {
"type": "string"
},
"serviceCatalogTitleRegExp": {
"type": "string"
},
"incidentTitleRegExp": {
"type": "string"
},
"inclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFileNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"type",
"syncMode",
"secretArn",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
}
```
### ServiceNow JSON schema example for using the configuration property with AWS CloudFormation
ServiceNow JSON schema example
The following is the ServiceNow JSON schema example for the configuration property for CloudFormation
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "CloudFormation SERVICENOW Data Source Template",
"Resources": {
"DataSourceServiceNow": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": "app12345-1234-1234-1234-123456789012",
"IndexId": "indx1234-1234-1234-1234-123456789012",
"DisplayName": "MyServiceNowDataSource",
"RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role",
"Configuration": {
"type": "SERVICENOWV2",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-servicenow-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"hostUrl": "mycompany.service-now.com",
"authType": "basicAuth",
}
},
"repositoryConfigurations": {
"knowledgeArticle": {
"fieldMappings": [
{
"indexFieldName": "article_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"attachment": {
"fieldMappings": [
{
"indexFieldName": "attachment_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"serviceCatalog": {
"fieldMappings": [
{
"indexFieldName": "catalog_item_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
},
"incident": {
"fieldMappings": [
{
"indexFieldName": "incident_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"maxFileSizeInMegaBytes": "50",
"isCrawlKnowledgeArticle": "true",
"isCrawlKnowledgeArticleAttachment": "true",
"includePublicArticlesOnly": "false",
"knowledgeArticleFilter": "filter_condition",
"incidentQueryFilter": "incident_condition",
"serviceCatalogQueryFilter": "service_catalog_condition",
"isCrawlServiceCatalog": "true",
"isCrawlServiceCatalogAttachment": "true",
"isCrawlActiveServiceCatalog": "true",
"isCrawlInactiveServiceCatalog": "false",
"isCrawlIncident": "true",
"isCrawlIncidentAttachment": "false",
"isCrawlActiveIncident": "true",
"isCrawlInactiveIncident": "false",
"applyACLForKnowledgeArticle": "true",
"applyACLForServiceCatalog": "true",
"applyACLForIncident": "true",
"incidentStateType": ["Open", "Resolved"],
"knowledgeArticleTitleRegExp": ".*",
"serviceCatalogTitleRegExp": ".*",
"incidentTitleRegExp": ".*",
"inclusionFileTypePatterns": ["*.pdf", "*.docx"],
"exclusionFileTypePatterns": ["*.tmp"],
"inclusionFileNamePatterns": ["important-*"],
"exclusionFileNamePatterns": ["temporary-*"],
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
}
}
}
}
```
## ServiceNow YAML schema for using the configuration property with AWS CloudFormation
ServiceNow YAML schema
The following is the ServiceNow YAML schema and examples for the configuration property for AWS CloudFormation:
**Topics**
+ [
### ServiceNow YAML schema for using the configuration property with AWS CloudFormation
](#servicenow-cfn-yaml-schema)
+ [
### ServiceNow YAML schema example for using the configuration property with AWS CloudFormation
](#servicenow-cfn-yaml-example)
### ServiceNow YAML schema for using the configuration property with AWS CloudFormation
ServiceNow YAML schema
The following is the ServiceNow YAML schema for the configuration property for CloudFormation.
```
type: object
properties:
type:
type: string
enum:
- SERVICENOWV2
- SERVICENOW
syncMode:
type: string
enum:
- FORCED_FULL_CRAWL
- FULL_CRAWL
secretArn:
type: string
minLength: 20
maxLength: 2048
enableIdentityCrawler:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
connectionConfiguration:
type: object
properties:
repositoryEndpointMetadata:
type: object
properties:
hostUrl:
type: string
pattern: "^(?!(^(https?|ftp|file):\\/\\/))[a-z0-9-]+(.service-now.com|.servicenowservices.com)$"
minLength: 1
maxLength: 2048
authType:
type: string
enum:
- basicAuth
- OAuth2
required:
- hostUrl
- authType
required:
- repositoryEndpointMetadata
repositoryConfigurations:
type: object
properties:
knowledgeArticle:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- STRING_LIST
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
attachment:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- LONG
- DATE
- STRING_LIST
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
serviceCatalog:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- STRING_LIST
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
incident:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- DATE
- STRING_LIST
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
additionalProperties:
type: object
properties:
maxFileSizeInMegaBytes:
type: string
isCrawlKnowledgeArticle:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlKnowledgeArticleAttachment:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
includePublicArticlesOnly:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
knowledgeArticleFilter:
type: string
incidentQueryFilter:
type: string
serviceCatalogQueryFilter:
type: string
isCrawlServiceCatalog:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlServiceCatalogAttachment:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlActiveServiceCatalog:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlInactiveServiceCatalog:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlIncident:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlIncidentAttachment:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlActiveIncident:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
isCrawlInactiveIncident:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
applyACLForKnowledgeArticle:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
applyACLForServiceCatalog:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
applyACLForIncident:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
incidentStateType:
type: array
items:
type: string
enum:
- Open
- Open - Unassigned
- Resolved
- All
knowledgeArticleTitleRegExp:
type: string
serviceCatalogTitleRegExp:
type: string
incidentTitleRegExp:
type: string
inclusionFileTypePatterns:
type: array
items:
type: string
exclusionFileTypePatterns:
type: array
items:
type: string
inclusionFileNamePatterns:
type: array
items:
type: string
exclusionFileNamePatterns:
type: array
items:
type: string
enableDeletionProtection:
anyOf:
- type: boolean
- type: string
enum:
- "true"
- "false"
default: false
deletionProtectionThreshold:
type: string
default: "15"
required: []
version:
type: string
anyOf:
- pattern: "1.0.0"
required:
- type
- syncMode
- secretArn
- connectionConfiguration
- repositoryConfigurations
- additionalProperties
```
### ServiceNow YAML schema example for using the configuration property with AWS CloudFormation
ServiceNow JSON schema example
The following is the ServiceNow YAML example for the Configuration property for CloudFormation:
```
AWSTemplateFormatVersion: "2010-09-09"
Description: CloudFormation SERVICENOW Data Source Template
Resources:
DataSourceServiceNow:
Type: AWS::QBusiness::DataSource
Properties:
ApplicationId: app12345-1234-1234-1234-123456789012
IndexId: indx1234-1234-1234-1234-123456789012
DisplayName: MyServiceNowDataSource
RoleArn: arn:aws:iam::123456789012:role/qbusiness-data-source-role
Configuration:
type: SERVICENOWV2
syncMode: FULL_CRAWL
secretArn: arn:aws:secretsmanager:us-west-2:123456789012:secret:my-servicenow-secret
enableIdentityCrawler: "true"
connectionConfiguration:
repositoryEndpointMetadata:
hostUrl: mycompany.service-now.com
authType: basicAuth
repositoryConfigurations:
knowledgeArticle:
fieldMappings:
- indexFieldName: article_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
attachment:
fieldMappings:
- indexFieldName: attachment_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
serviceCatalog:
fieldMappings:
- indexFieldName: catalog_item_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
incident:
fieldMappings:
- indexFieldName: incident_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
additionalProperties:
maxFileSizeInMegaBytes: "50"
isCrawlKnowledgeArticle: "true"
isCrawlKnowledgeArticleAttachment: "true"
includePublicArticlesOnly: "false"
knowledgeArticleFilter: filter_condition
incidentQueryFilter: incident_condition
serviceCatalogQueryFilter: service_catalog_condition
isCrawlServiceCatalog: "true"
isCrawlServiceCatalogAttachment: "true"
isCrawlActiveServiceCatalog: "true"
isCrawlInactiveServiceCatalog: "false"
isCrawlIncident: "true"
isCrawlIncidentAttachment: "false"
isCrawlActiveIncident: "true"
isCrawlInactiveIncident: "false"
applyACLForKnowledgeArticle: "true"
applyACLForServiceCatalog: "true"
applyACLForIncident: "true"
incidentStateType:
- Open
- Resolved
knowledgeArticleTitleRegExp: ".*"
serviceCatalogTitleRegExp: ".*"
incidentTitleRegExp: ".*"
inclusionFileTypePatterns:
- "*.pdf"
- "*.docx"
exclusionFileTypePatterns:
- "*.tmp"
inclusionFileNamePatterns:
- important-*
exclusionFileNamePatterns:
- temporary-*
enableDeletionProtection: "false"
deletionProtectionThreshold: "15"
```
# How Amazon Q Business connector crawls ServiceNow ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an ServiceNow data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your ServiceNow instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level.
**Note**
Amazon Q Business supports:
Role-based, static ACLs for Service Catalogs
Role-based, static ACLs for Knowledge Bases
Role-based, static ACLs for Incidents
Amazon Q Business does not honor limitations set by ServiceNow's advanced ACLs on documents.
The group and user IDs are mapped as follows:
+ `_group_ids` – Group IDs exist in ServiceNow on files where there are set access permissions. They're mapped from the role names of `sys_ids` in ServiceNow.
+ `_user_id` – User IDs exist in ServiceNow on files where there are set access permissions. They're mapped from the user emails as the IDs in ServiceNow.
**Important**
To maintain secure access control for Amazon Q Business, each user must have a unique email address across all connected data sources.
In ServiceNow users can share an email address while having a different application-specific unique identifier. However, in Amazon Q Business email addresses act as unique identifiers.
This means that if a document is shared with a particular user (for example, arnav\$1desai@example.com who is part of pentesters@example.com) on the basis of an application-specific unique ID, every other user who shares pentesters@example.com (for example, xiulan\$1wang@example.com and efua\$1owusu@example.com, both of whom are part of pentesters@example.com) can receive Amazon Q Business responses with content from a document that was shared only with Arnav. Similarly, content created by Arnav that only he should be able to access via Amazon Q Business chat responses, could also be part of Amazon Q Business chat responses for Xiulan and Efua, because they share the same email address.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# ServiceNow Online data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q ServiceNow connector supports the following entities and the associated reserved and custom attributes.
**Topics**
+ [
## Knowledge articles
](#servicenow-field-mappings-ka)
+ [
## Service catalog
](#servicenow-field-mappings-sc)
+ [
## Attachments
](#servicenow-field-mappings-attachment)
+ [
## Incidents
](#servicenow-field-mappings-incidents)
## Knowledge articles
Amazon Q supports crawling [ServiceNow Online Knowledge articles](https://docs.servicenow.com/bundle/xanadu-servicenow-platform/page/product/knowledge-management/task/create-knowledge-article.html) and offers the following knowledge article field mappings.
| ServiceNow field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| text | sn\$1ka\$1text | Custom | String |
| short\$1description | sn\$1ka\$1short\$1description | Custom | String |
| sys\$1created\$1on | \$1created\$1at | Default | Date |
| sys\$1updated\$1on | \$1last\$1updated\$1at | Default | Date |
| kb\$1category\$1name | \$1category | Default | String |
| sys\$1created\$1by | \$1authors | Default | String |
| sys\$1updated\$1by | sn\$1updatedBy | Custom | String |
| sys\$1id | sn\$1sys\$1id | Custom | String |
| published | sn\$1ka\$1publish\$1date | Custom | Date |
| workflow\$1state | sn\$1ka\$1workflow\$1state | Custom | String |
| kb\$1category | sn\$1ka\$1category | Custom | String |
| article\$1type | sn\$1ka\$1article\$1type | Custom | String |
| first\$1name | sn\$1ka\$1first\$1name | Custom | String |
| last\$1name | sn\$1ka\$1last\$1name | Custom | String |
| user\$1name | sn\$1ka\$1user\$1name | Custom | String |
| valid\$1to | sn\$1ka\$1valid\$1to | Custom | Date |
| kb\$1knowledge\$1base | sn\$1ka\$1knowledge\$1base | Custom | String |
| number | sn\$1ka\$1number | Custom | String |
| url | sn\$1url | Custom | String |
| diplayUrl | \$1source\$1uri | Default | String |
| replacement\$1article | sn\$1ka\$1replacement\$1article | Custom | String |
| description | sn\$1ka\$1description | Custom | String |
| wiki | sn\$1ka\$1wiki | Custom | String |
| rating | sn\$1ka\$1rating | Custom | String |
| rating | sn\$1ka\$1rating | Custom | String |
| view\$1as\$1allowed | sn\$1ka\$1view\$1as\$1allowed | Custom | String |
| source | sn\$1ka\$1source | Custom | String |
| image | sn\$1ka\$1image | Custom | String |
| author | sn\$1ka\$1author | Custom | String |
| active | sn\$1ka\$1active | Custom | String |
| helpful\$1count | sn\$1ka\$1helpful\$1count | Custom | String |
| meta\$1description | sn\$1ka\$1meta\$1description | Custom | String |
| meta | sn\$1ka\$1meta | Custom | String |
| topic | sn\$1ka\$1topic | Custom | String |
| roles | sn\$1ka\$1roles | Custom | String |
| disable\$1suggesting | sn\$1ka\$1disable\$1suggesting | Custom | String |
| use\$1count | sn\$1ka\$1use\$1count | Custom | String |
| flagged | sn\$1ka\$1flagged | Custom | String |
| disable\$1commenting | sn\$1ka\$1disable\$1commenting | Custom | String |
| retired | sn\$1ka\$1retired | Custom | String |
| display\$1attachments | sn\$1ka\$1display\$1attachments | Custom | String |
| taxonomy\$1topic | sn\$1ka\$1taxonomy\$1topic | Custom | String |
## Service catalog
Amazon Q supports crawling [ServiceNow Online service catalogs](https://docs.servicenow.com/bundle/vancouver-servicenow-platform/page/product/service-catalog-management/concept/service-catalog.html) and offers the following service catalog field mappings.
| ServiceNow field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| description | sn\$1sc\$1description | Custom | String |
| short\$1description | sn\$1sc\$1short\$1description | Custom | String |
| sys\$1created\$1on | \$1created\$1at | Default | Date |
| sys\$1updated\$1on | \$1last\$1updated\$1at | Default | Date |
| category\$1name | \$1category | Default | String |
| sys\$1created\$1by | \$1authors | Default | String list |
| sys\$1updated\$1by | sn\$1updated\$1by | Custom | String |
| sys\$1id | sn\$1sys\$1id | Custom | String |
| sc\$1catalogs | sn\$1sc\$1catalogs | Custom | String |
| sc\$1catalogs\$1name | sn\$1sc\$1catalogs\$1name | Custom | String |
| category | sn\$1sc\$1category | Custom | String |
| category\$1full\$1name | sn\$1sc\$1category | Custom | String |
| url | sn\$1url | Custom | String |
| displayUrl | \$1source\$1uri | Default | String |
| show\$1variable\$1help\$1on\$1load | sn\$1sc\$1show\$1var\$1help\$1on\$1load | Custom | String |
| no\$1order\$1now | sn\$1sc\$1no\$1order\$1now | Custom | String |
| sc\$1ic\$1version | sn\$1sc\$1sc\$1ic\$1version | Custom | String |
| delivery\$1time | sn\$1sc\$1deliver\$1time | Custom | String |
| published\$1ref | sn\$1sc\$1published\$1ref | Custom | String |
| price | sn\$1sc\$1price | Custom | String |
| recurring\$1frequency | sn\$1sc\$1recurring\$1frequency | Custom | String |
| sys\$1name | sn\$1sc\$1sys\$1name | Custom | String |
| model | sn\$1sc\$1model | Custom | String |
| state | sn\$1sc\$1state | Custom | String |
| no\$1cart | sn\$1sc\$1no\$1cart | Custom | String |
| group | sn\$1sc\$1group | Custom | String |
| hide\$1sp | sn\$1sc\$1hide\$1sp | Custom | String |
| order | sn\$1sc\$1order | Custom | String |
| start\$1closed | sn\$1sc\$1start\$1closed | Custom | String |
| image | sn\$1sc\$1image | Custom | String |
| no\$1quantity | sn\$1sc\$1no\$1quantity | Custom | String |
| delivery\$1plan | sn\$1sc\$1delivery\$1plan | Custom | String |
| active | sn\$1sc\$1active | Custom | String |
| checked\$1out | sn\$1sc\$1checked\$1out | Custom | String |
| custom\$1cart | sn\$1sc\$1custom\$1cart | Custom | String |
| no\$1cart\$1v2 | sn\$1sc\$1no\$1cart\$1v2 | Custom | String |
| no\$1proceed\$1checkout | sn\$1sc\$1no\$1proceed\$1checkout | Custom | String |
| ignore\$1price | sn\$1sc\$1ignore\$1price | Custom | String |
| sys\$1update\$1name | sn\$1sc\$1sys\$1update\$1name | Custom | String |
| meta | sn\$1sc\$1meta | Custom | String |
| omit\$1price | sn\$1sc\$1omit\$1price | Custom | String |
| name | sn\$1sc\$1name | Custom | String |
| mobile\$1hide\$1price | sn\$1sc\$1mobile\$1hide\$1price | Custom | String |
| no\$1wishlist\$1v2 | sn\$1sc\$1no\$1wishlist\$1v2 | Custom | String |
| preview | sn\$1sc\$1preview | Custom | String |
| type | sn\$1sc\$1type | Custom | String |
| access\$1type | sn\$1sc\$1access\$1type | Custom | String |
| roles | sn\$1sc\$1roles | Custom | String |
| icon | sn\$1sc\$1icon | Custom | String |
| mobile\$1picture | sn\$1sc\$1mobile\$1picture | Custom | String |
| availability | sn\$1sc\$1availability | Custom | String |
| mandatory\$1attachment | sn\$1sc\$1mandatory\$1attachment | Custom | String |
| request\$1method | sn\$1sc\$1request\$1method | Custom | String |
| visible\$1guide | sn\$1sc\$1visible\$1guide | Custom | String |
| visible\$1standalone | sn\$1sc\$1visible\$1standalone | Custom | String |
| no\$1order | sn\$1sc\$1no\$1order | Custom | String |
| vendor | sn\$1sc\$1vendor | Custom | String |
| no\$1attachment\$1v2 | sn\$1sc\$1no\$1attachment\$1v2 | Custom | String |
| mobile\$1picture\$1type | sn\$1sc\$1mobile\$1picture\$1type | Custom | String |
| visible\$1bundle | sn\$1sc\$1visible\$1bundle | Custom | String |
| ordered\$1item\$1link | sn\$1sc\$1ordered\$1item\$1link | Custom | String |
| owner | sn\$1sc\$1owner | Custom | String |
| no\$1delivery\$1time\$1v2 | sn\$1sc\$1no\$1delivery\$1time\$1v2 | Custom | String |
| cost | sn\$1sc\$1cost | Custom | String |
| no\$1quantity\$1v2 | sn\$1sc\$1no\$1quantity\$1v2 | Custom | String |
| recurring\$1price | sn\$1sc\$1recurring\$1price | Custom | String |
| list\$1price | sn\$1sc\$1list\$1price | Custom | String |
| syst\$1tags | sn\$1sc\$1sys\$1tags | Custom | String |
| billable | sn\$1sc\$1billable | Custom | String |
| picture | sn\$1sc\$1picture | Custom | String |
| display\$1price\$1property | sn\$1sc\$1display\$1price\$1property | Custom | String |
| taxonomy\$1topic | sn\$1sc\$1taxonomy\$1topic | Custom | String |
| delivery\$1plain\$1script | sn\$1sc\$1delivery\$1plain\$1script | Custom | String |
| location | sn\$1sc\$1location | Custom | String |
## Attachments
Amazon Q supports crawling [ServiceNow Online attachments](https://docs.servicenow.com/bundle/tokyo-platform-user-interface/page/use/using-forms/task/t_AddingAnAttachment.html) and offers the following attachment field mappings.
| ServiceNow field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| size\$1bytes | sn\$1file\$1size | Custom | Long (numeric) |
| file\$1name | sn\$1file\$1name | Custom | String |
| sys\$1mod\$1count | sn\$1sys\$1mod\$1count | Custom | String |
| average\$1image\$1color | sn\$1average\$1image\$1color | Custom | String |
| image\$1width | sn\$1image\$1width | Custom | String |
| sys\$1updated\$1on | \$1last\$1updated\$1at | Default | Date |
| sys\$1tags | sn\$1sys\$1tags | Custom | String |
| table\$1name | sn\$1table\$1name | Custom | String |
| sys\$1id | sn\$1sys\$1id | Custom | String |
| image\$1height | sn\$1image\$1height | Custom | String |
| sys\$1updated\$1by | sn\$1updated\$1by | Custom | String |
| content\$1type | sn\$1content\$1type | Custom | String |
| sys\$1created\$1on | \$1created\$1at | Default | Date |
| size\$1compressed | sn\$1size\$1compressed | Custom | String |
| compressed | sn\$1compressed | Custom | String |
| state | sn\$1state | Custom | String |
| table\$1sys\$1id | sn\$1table\$1sys\$1id | Custom | String |
| chunk\$1size\$1bytes | sn\$1chunk\$1size\$1bytes | Custom | String |
| hash | sn\$1hash | Custom | String |
| sys\$1created\$1by | \$1authors | Default | String list |
| sys\$1updated\$1by | sn\$1updated\$1by | Custom | String |
| url | sn\$1url | Custom | String |
| displayUrl | \$1source\$1uri | Default | String |
## Incidents
Amazon Q supports crawling [ServiceNow Online incidents](https://docs.servicenow.com/bundle/tokyo-it-service-management/page/product/incident-management/concept/c_IncidentManagement.html) and offers the following incident field mappings.
| ServiceNow field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| short\$1description | sn\$1inc\$1short\$1description | Custom | String |
| description | sn\$1inc\$1description | Custom | String |
| sys\$1updated\$1on | \$1last\$1updated\$1at | Default | Date |
| number | sn\$1inc\$1number | Custom | String |
| sys\$1updated\$1by | sn\$1updatedBy | Custom | String |
| displayUrl | \$1source\$1uri | Default | String |
| opened\$1by | sn\$1inc\$1opened\$1by | Custom | String |
| sys\$1created\$1on | \$1created\$1at | Default | Date |
| state | sn\$1inc\$1state | Custom | String |
| sys\$1created\$1by | \$1authors | Default | String list |
| business\$1impact | sn\$1inc\$1business\$1impact | Default | String |
| impact | sn\$1inc\$1business\$1impact | Custom | String |
| priority | sn\$1inc\$1priority | Custom | String |
| urgency | sn\$1inc\$1urgency | Custom | String |
| opened\$1at | an\$1inc\$1opened\$1at | Custom | String |
| business\$1duration | sn\$1inc\$1business\$1duration | Custom | String |
| caller\$1id | sn\$1inc\$1caller\$1id | Custom | String |
| resolved\$1at | sn\$1inc\$1resolved\$1at | Custom | String |
| category | sn\$1inc\$1category | Custom | String |
| subcategory | sn\$1inc\$1subcategory | Custom | String |
| close\$1code | sn\$1inc\$1close\$1code | Custom | String |
| assignment\$1group | sn\$1inc\$1assignment\$1group | Custom | String |
| close\$1notes | sn\$1inc\$1close\$1notes | Custom | String |
| displayUrl | \$1source\$1uri | Default | String |
| sys\$1class\$1name | sn\$1inc\$1sys\$1class\$1name | Custom | String |
| parent\$1incident | an\$1inc\$1parent\$1incident | Custom | String |
| incident\$1state | sn\$1incident\$1state | Custom | String |
| company | sn\$1inc\$1company | Custom | String |
| assigned\$1to | sn\$1inc\$1assigned\$1to | Custom | String |
| hold\$1reason | an\$1inc\$1hold\$1reason | Custom | String |
| work\$1notes | sn\$1inc\$1work\$1notes | Custom | String |
| comments\$1and\$1work\$1notes | sn\$1inc\$1comments\$1and\$1work\$1notes | Custom | String |
| work\$1notes\$1list | sn\$1work\$1notes\$1list | Custom | String |
| comments | sn\$1inc\$1comments | Custom | String |
| sys\$1id | sn\$1inc\$1sys\$1id | Custom | String |
| url | sn\$1url | Custom | String |
| active | sn\$1inc\$1active | Custom | String |
| activity\$1due | sn\$1inc\$1activity\$1due | Custom | String |
| additional\$1assignee\$1list | sn\$1inc\$1additional\$1assign\$1list | Custom | String |
| approval | sn\$1inc\$1approval | Custom | String |
| approval\$1history | sn\$1inc\$1approval\$1history | Custom | String |
| approval\$1set | sn\$1inc\$1approval\$1set | Custom | Date |
| business\$1service | sn\$1inc\$1business\$1service | Custom | String |
| closed\$1by | sn\$1inc\$1closed\$1by | Custom | String |
| cmdb\$1ci | sn\$1inc\$1cmdb\$1id | Custom | String |
| resolved\$1by | sn\$1inc\$1resolved\$1by | Custom | String |
| sys\$1domain | sn\$1inc\$1sys\$1domain | Custom | String |
| business\$1stc | sn\$1inc\$1business\$1stc | Custom | String |
| calendar\$1duration | sn\$1inc\$1calendar\$1duration | Custom | String |
| calendar\$1stc | sn\$1inc\$1calendar\$1stc | Custom | String |
| cause | sn\$1inc\$1cause | Custom | String |
| caused\$1by | sn\$1inc\$1caused\$1by | Custom | String |
| child\$1incidents | sn\$1inc\$1child\$1incidents | Custom | String |
| closed\$1at | sn\$1inc\$1closed\$1at | Custom | String |
| contact\$1type | sn\$1inc\$1contact\$1type | Custom | String |
| contract | sn\$1inc\$1contract | Custom | String |
| correlation\$1display | sn\$1inc\$1correlation\$1display | Custom | String |
| delivery\$1plan | sn\$1inc\$1delivery\$1plan | Custom | String |
| delivery\$1task | sn\$1inc\$1delivery\$1task | Custom | String |
| due\$1date | sn\$1inc\$1due\$1date | Custom | String |
| escalation | sn\$1inc\$1escalation | Custom | String |
| expected\$1start | sn\$1inc\$1expected\$1start | Custom | String |
| follow\$1up | sn\$1inc\$1follow\$1up | Custom | String |
| group\$1list | sn\$1inc\$1group\$1list | Custom | String |
| knowledge | sn\$1inc\$1knowledge | Custom | String |
| location | sn\$1inc\$1location | Custom | String |
| made\$1sla | sn\$1inc\$1made\$1sla | Custom | String |
| notify | sn\$1inc\$1notify | Custom | String |
| order | sn\$1inc\$1order | Custom | String |
| origin\$1id | sn\$1inc\$1origin\$1id | Custom | String |
| origin\$1table | sn\$1inc\$1origin\$1table | Custom | String |
| parent | sn\$1inc\$1parent | Custom | String |
| problem\$1id | sn\$1inc\$1problem\$1id | Custom | String |
| reassignment\$1count | sn\$1inc\$1reassignment\$1count | Custom | String |
| repoen\$1count | sn\$1inc\$1reopen\$1count | Custom | String |
| reopened\$1by | sn\$1inc\$1reopened\$1by | Custom | String |
| reopened\$1time | sn\$1inc\$1reopened\$1time | Custom | String |
| rfc | sn\$1inc\$1rfc | Custom | String |
| route\$1reason | sn\$1inc\$1route\$1reason | Custom | String |
| service\$1offering | sn\$1inc\$1service\$1offering | Custom | String |
| severity | sn\$1inc\$1severity | Custom | String |
| sla\$1due | sn\$1inc\$1sla\$1due | Custom | Date |
| task\$1effective\$1number | sn\$1inc\$1task\$1effective\$1number | Custom | String |
| time\$1worked | sn\$1inc\$1time\$1worked | Custom | Date |
| universal\$1request | sn\$1inc\$1universal\$1request | Custom | String |
| upon\$1approval | sn\$1inc\$1upon\$1approval | Custom | String |
| upon\$1reject | sn\$1inc\$1upon\$1reject | Custom | String |
| user\$1input | sn\$1inc\$1user\$1input | Custom | String |
| watch\$1list | sn\$1inc\$1watch\$1list | Custom | String |
| work\$1end | sn\$1inc\$1work\$1end | Custom | String |
| work\$1start | sn\$1inc\$1work\$1start | Custom | String |
# IAM role for Amazon Q Business ServiceNow Online connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Understand error codes in the Amazon Q Business ServiceNow Online connector
Error Codes
The following table provides information about error codes you may see for the ServiceNow Online connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| SRN-5001 | Error validating credentials due to invalid client id or client secret or username or password. | Provide a valid client id/client secret/username/password. |
| SRN-5002 | Error validating credentials due to invalid username or password. | Provide a valid username/password. |
| SRN-5003 | Access token is empty or null. | Provide a non empty or non null access token. |
| SRN-5004 | Client ID exceeded the allowed length. | Provide a valid Client ID. |
| SRN-5005 | Client Secret exceeded the allowed length. | Provide a valid Client Secret. |
| SRN-5006 | Password exceeded the allowed length. | Provide a valid Password. |
| SRN-5007 | clientSecret contains non-printable Ascii characters. | Provide a valid clientSecret. |
| SRN-5008 | clientId contains non-printable Ascii characters. | Provide a valid clientId. |
| SRN-5010 | Error validating credentials due to invalid username or password. | Provide a valid username/password. |
| SRN-5011 | Amazon Q can't connect to the ServiceNow server with the specified credentials. | Provide admin credentials and try your request again. |
| SRN-5014 | ServiceNow instance is not available. | Check your ServiceNow instance before crawling. |
| SRN-5100 | Client id should not be empty. | Provide a valid client id. |
| SRN-5101 | Client secret should not be empty. | Provide a valid client secret. |
| SRN-5102 | User name should not be empty. | Provide a valid username. |
| SRN-5103 | Password should not be empty. | Provide a valid password. |
| SRN-5104 | Auth type should not be empty. | Provide an auth Type. |
| SRN-5105 | Incorrect auth type. | Auth type should be basicAuth or OAuth2. |
| SRN-5106 | Host url should not be empty. | Provide a valid host url. |
| SRN-5120 | crawlType should not be empty. | crawlType should be FORCED\$1FULL\$1CRAWL or FULL\$1CRAWL or CHANGE\$1LOG. |
| SRN-5122 | isCrawlKnowledgeArticle should not be empty. | Provide valid isCrawlKnowledgeArticle. |
| SRN-5123 | Invalid isCrawlKnowledgeArticle value. | isCrawlKnowledgeArticle should be true or false. |
| SRN-5124 | isCrawlKnowledgeArticleAttachment should not be empty. | Provide valid isCrawlKnowledgeArticleAttachment. |
| SRN-5125 | Invalid isCrawlKnowledgeArticleAttachment value. | isCrawlKnowledgeArticleAttachment should be true or false. |
| SRN-5126 | isCrawlServiceCatalog should not be empty. | Provide valid isCrawlServiceCatalog. |
| SRN-5127 | invalid isCrawlServiceCatalog value. | isCrawlServiceCatalog should be true or false. |
| SRN-5128 | isCrawlServiceCatalogAttachment should not be empty. | Provide valid isCrawlServiceCatalogAttachment. |
| SRN-5129 | Invalid isCrawlServiceCatalogAttachment value. | isCrawlServiceCatalogAttachment should be true or false. |
| SRN-5130 | isCrawlIncident should not be empty. | Provide valid isCrawlIncident. |
| SRN-5131 | invalid isCrawlIncident value. | isCrawlIncident should be true or false. |
| SRN-5132 | isCrawlIncidentAttachment should not be empty. | Provide valid isCrawlIncidentAttachment. |
| SRN-5133 | Invalid isCrawlIncidentAttachment value. | isCrawlIncidentAttachment should be true or false. |
| SRN-5134 | Invalid incidentStateType. | Invalid incidentStateType. Incident State Type should be All, Open, Open - Unassigned or Resolved. |
| SRN-5135 | applyACLForKnowledgeArticle should not be empty. | Provide valid applyACLForKnowledgeArticle. |
| SRN-5136 | applyACLForServiceCatalog should not be empty. | Provide valid applyACLForServiceCatalog. |
| SRN-5137 | applyACLForIncident should not be empty. | Provide valid applyACLForIncident. |
| SRN-5138 | Invalid applyACLForKnowledgeArticle value. | applyACLForKnowledgeArticle should be true or false. |
| SRN-5139 | Invalid applyACLForServiceCatalog value. | applyACLForServiceCatalog should be true or false. |
| SRN-5140 | Invalid applyACLForIncident value. | applyACLForIncident should be true or false. |
| SRN-5141 | invalid pattern :”file type pattern” | Provide valid patterns. |
| SRN-5142 | includePublicArticlesOnly should not be empty. | Provide valid includePublicArticlesOnly. |
| SRN-5143 | Invalid includePublicArticlesOnly value. | includePublicArticlesOnly should be true or false. |
| SRN-5144 | Invalid URI. | Provide valid URI. |
| SRN-5145 | isCrawlActiveServiceCatalog should not be empty. | Provide valid isCrawlActiveServiceCatalog. |
| SRN-5146 | isCrawlInActiveServiceCatalog should not be empty. | Provide valid isCrawlInactiveServiceCatalog. |
| SRN-5147 | isCrawlActiveIncident should not be empty. | Provide valid isCrawlActiveIncident. |
| SRN-5148 | isCrawlInActiveIncident should not be empty. | Provide valid isCrawlInactiveIncident. |
| SRN-5149 | Invalid isCrawlActiveServiceCatalog value. | isCrawlActiveServiceCatalog should be true or false. |
| SRN-5150 | Invalid isCrawlInactiveServiceCatalog value. | isCrawlInactiveServiceCatalog should be true or false. |
| SRN-5151 | Invalid isCrawlActiveIncident value. | isCrawlActiveIncident should be true or false. |
| SRN-5152 | Invalid isCrawlInactiveIncident value. | isCrawlInactiveIncident should be true or false. |
| SRN-5153 | servicenowInstanceVersion should not be empty. | Provide a valid servicenowInstanceVersion. |
| SRN-5154 | The ServiceNow host name is invalid. | The ServiceNow host name should follow the format: example.service-now.com |
| SRN-5501 | continuableInternalServerError. | Try again later. |
# Connecting Slack to Amazon Q Business
Slack
Slack is an enterprise communications app that lets users send messages and attachments through various public and private channels. You can connect your Slack instance to Amazon Q Business—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# Known limitations for the Slack connector
](slack-limitations.md)
+ [
# Slack connector overview
](slack-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Slack
](slack-prereqs.md)
+ [
# Setting up Slack for connecting to Amazon Q
](slack-credentials.md)
+ [
# Connecting Amazon Q Business to Slack using the console
](slack-console.md)
+ [
# Connecting Amazon Q Business to Slack using APIs
](slack-api.md)
+ [
# Connecting Amazon Q Business to Slack using AWS CloudFormation
](slack-cfn.md)
+ [
# How Amazon Q Business connector crawls Slack ACLs
](slack-user-management.md)
+ [
# Slack data source connector field mappings
](slack-field-mappings.md)
+ [
# IAM role for the Slack connector
](slack-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Slack connector
Known limitations
The Slack connector has the following known limitations:
+ Due to API limitations, the Amazon Q Slack connector can only retrieve a maximum of 100 pages, with 100 files per page. Given this limitation, the Slack connector can only crawl a maximum of 10,000 files per channel.
# Slack connector overview
Overview
The following table gives an overview of the Amazon Q Business Slack connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/slack-overview.html)
# Prerequisites for connecting Amazon Q Business to Slack
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Slack, make sure you have:**
+ Created a Slack Bot User OAuth token or Slack User OAuth token. You can choose either token to connect Amazon Q to your Slack data source. See [Slack documentation on access tokens](https://api.slack.com/authentication/token-types) for more information.
**Note**
If you use the bot token as part of your Slack credentials, you cannot index direct messages and group messages. You must add the bot token to the channel you want to index.
+ Noted your Slack workspace team ID from your Slack workspace main page URL. For example, *https://app.slack.com/client/T0123456789/... * where *T0123456789* is the team ID.
+ Added the required OAuth scopes/ read permissions. See [Setting up Slack](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/slack-credentials.html) for more details.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Slack authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
**Note**
For more information on connecting Slack to Amazon Q Business, see [Unlock the knowledge in your Slack workspace with Slack connector for Amazon Q Business](https://aws.amazon.com/blogs/machine-learning/unlock-the-knowledge-in-your-slack-workspace-with-slack-connector-for-amazon-q-business/) in the *AWS Machine Learning Blog*.
# Setting up Slack for connecting to Amazon Q
Setting up Slack
Before you connect Slack to Amazon Q, you need to create and retrieve the Slack credentials you will use to connect Slack to Amazon Q. You will also need to add any permissions needed by Slack to connect to Amazon Q.
The following procedure gives you an overview of how to configure Slack for connecting with Amazon Q.
**Configuring Slack authentication for Amazon Q**
1. Log in to your [Slack account](https://slack.com/signin) and sign into your Slack workspace.
**Note**
To configure Slack for Amazon Q, you must be an admin user in the Slack account.
1. From the workspace menu, select **Tools and settings** and then select **Manage apps**.
![\[Screenshot of the Slack workspace menu showing how to access the App Directory to create a new app for integration.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/slack-1.png)
1. From the **Slack App Directory** menu, select **Build**.
![\[Screenshot of the Slack App Directory menu with the "Build" option highlighted, which is used to create a new app for integration.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/slack-2.png)
1. On the **Your Apps** page, select **Create an App**.
![\[Screenshot of the Slack "Your Apps" page showing the "Create an App" button that users need to click to begin creating a new Slack app.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/slack-3.png)
1. On the **Create an app** page, select **From scratch**.
![\[Screenshot of the Slack "Create an app" page showing the "From scratch" option that allows users to create a new app from the beginning.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/slack-4.png)
1. In the **Name app & choose workspace** dialog box that opens, add an **App name** and **Pick a workspace to deploy your app in**. Then select **Create App**.
![\[Screenshot of the "Name app & choose workspace" dialog box where users enter an app name and select a workspace for deployment.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/slack-11.png)
1. On the **Basic Information** page, from the **Settings** menu, select **OAuth & Permissions**.
![\[Screenshot of the Slack app's "Basic Information" page with the "OAuth & Permissions" option highlighted in the Settings menu.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/slack-5.png)
1. On the **OAuth & Permissions** page, go to **Scopes**, and then do the following based on whether you want to use a Bot Token to connect Slack to Amazon Q, or a User Token:
**Important**
If you use the bot token as part of your Slack credentials, you cannot index direct messages and group messages, and you must add the bot token to the channel you want to index. For information on Slack token types, see [Token types](https://api.slack.com/authentication/token-types) in Slack API.
+ Add the following **Bot Token Scopes**:
![\[Screenshot of the Slack "OAuth & Permissions" page showing the Bot Token Scopes section where users can add permission scopes for the bot.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/slack-6.png)
+ `channels:history` – View messages and other content in public channels that your app has been added to
+ `channels:manage` – Manage public channels that your app has been added to and create new ones
+ `channels:read` – View basic information about public channels in a workspace
+ `conversations.connect:manage` – Receive Slack Connect invite events sent to the channels your app is in
+ `conversations.connect:read` – Receive Slack Connect invite events sent to the channels your app is in
+ `files:read` – View files shared in channels and conversations that your app has been added to
+ `groups:history` – View messages and other content in private channels that your app has been added to
+ `groups:read` – View basic information about private channels that your app has been added to
+ `im:history` – View messages and other content in direct messages that your app has been added to
+ `im:read` – View basic information about direct messages that your app has been added to
+ `mpim:history` – View messages and other content in group direct messages that your app has been added to
+ `mpim:read` – View basic information about group direct messages that your app has been added to
+ `reactions:read` – View emoji reactions and their associated content in channels and conversations that your app has been added to
+ `team:read` – View the name, email domain, and icon for workspaces your app is connected to
+ `usergroups:read` – Create and manage user groups
+ `users.profile:read` – View profile details about people in a workspace
+ `users:read` – View people in a workspace
+ `users:read.email` – View email addresses of people in a workspace
+ Add the following **User Token Scopes**:
![\[Screenshot of the Slack "OAuth & Permissions" page showing the User Token Scopes section where users can add permission scopes for user-level access.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/slack-7.png)
+ `channels:history` – View messages and other content in a user’s public channels
+ `channels:read` – View basic information about public channels in a workspace
+ `emoji:read` – View custom emoji in a workspace
+ `files:read` – View files shared in channels and conversations that a user has access to
+ `groups:history` – View messages and other content in a user’s private channels
+ `groups:read` – View basic information about a user’s private channels
+ `im:history` – View messages and other content in a user’s direct messages
+ `im:read` – View basic information about a user’s direct messages
+ `mpim:history` – View messages and other content in a user’s group direct messages
+ `mpim:read` – View basic information about a user’s group direct messages
+ `team:read` – View the name, email domain, and icon for workspaces a user is connected to
+ `users.profile:read` – View profile details about people in a workspace
+ `users:read.email` – View email addresses of people in a workspace
+ `users:read` – View people in a workspace
1. Then, scroll to **OAuth Tokens** section, and choose **Install to Workspace**.
![\[Screenshot of the Slack "OAuth & Permissions" page showing the "Install to Workspace" button that users need to click to install the app to their workspace.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/slack-8.png)
1. On the dialog box that opens up informing you that the app that you created is requesting permission to access the Slack workspace you wanted to connect it to, select **Allow**.
![\[Screenshot of the Slack permission request dialog box asking for authorization to access the workspace, with an "Allow" button for users to grant permissions.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/slack-9.png)
On successful completion, the console will display a **OAuth Tokens** screen.
1. From the **OAuth Tokens** screen, copy and save the OAuth token you will use to connect to Amazon Q—either **User OAuth Token** or **Bot User OAuth Token**. You input this as **Slack token** when you connect to Amazon Q.
![\[Screenshot of the Slack "OAuth Tokens" screen displaying the generated OAuth tokens that need to be copied for connecting to Amazon Q Business.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/slack-10.png)
1. Next, you retrieve your Slack team ID. You need this to connect to Amazon Q.
From the Slack workspace menu, select **Tools and settings** and then select **Manage apps**. You'll find your team ID in the URL of the page that opens.
![\[alt text not found\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/slack-1.png)
![\[Screenshot showing the URL of the Slack workspace management page with the team ID highlighted, which is needed for connecting to Amazon Q Business.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/slack-12.png)
You now have the Slack Team ID and Slack token you need to connect to Amazon Q.
# Connecting Amazon Q Business to Slack using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Slack using the AWS Management Console.
**Connecting Amazon Q to Slack**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Slack** data source to your Amazon Q application.
1. Then, on the **Slack** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **Source**, **Slack workspace team ID** – The team ID of your Slack workspace.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. For **Slack token** – Enter the authentication credential values you created in your Slack account.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/slack-connector.html#slack-iam).
1. In **Sync scope**, enter the following information:
1. **Select type of content to crawl** – Select any combination of **All channels**, **Public channels**, **Private channels**, **Group messages**, and **Private messages**.
1. **Select crawl start date** – Choose the date from which the Amazon Q connector will start crawling content.
1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB.
1. **Additional configuration – optional** – Configure the following settings:
+ In **Channels** (available only if you've chosen to crawl **Channels**), do the following:
+ **Channel ID/Name** – Choose between **Channel ID** and **Channel Name**.
**Note**
You can choose to configure both.
+ For **Channel ID** – Enter the **Channel ID**. The **Channel ID** filter applies to both public and private channels.
+ For **Channel Name** – Choose the **Channel type** and enter the **Channel name**. You can select between **Public channel** and **Private channel**.
**Note**
If you choose to configure filters for both **Channel ID** and **Channel Name**, the Amazon Q Slack connector will prioritize channel IDs over channel names.
If you choose to configure filters for either **Channel ID** or **Channel Name**, the Amazon Q Slack connector will ignore **Private** and **Group** messages even if you've chosen to crawl private and group messages in **Sync scope**.
+ In **Messages**, for **Select sync scope for content** – Choose to **Include bot messages**, and/or **Include archived messaged**.
+ **Regex patterns** – Add regex patterns to include or exclude file names or file types. You can add a total of 100 patterns. Examples of regex patterns include:
+ **File type** – .pdf, .docx
+ **File name** – Hello\$1.txt, TestFile.\$1
1. **Multi-media content configuration – optional** – To enable content extraction from embedded images and visuals in documents, choose **Visual content in documents**.
To extract audio transcriptions and video content, enable processing for the following file types:
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. For **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync**—Sync all content regardless of the previous sync status.
+ **New, modified, or deleted content sync**—Sync only new, modified, and deleted documents.
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Slack using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
**Topics**
+ [
## Slack configuration properties
](#slack-configuration-keys)
+ [
## Slack JSON schema
](#slack-json)
+ [
## Slack JSON schema example
](#s3-api-json-example)
## Slack configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has the following sub-property: `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-property: `teamId`. | Yes |
| `teamId` | The Slack team ID you copied from your Slack main page URL. | `string` | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-property: `All`. | No |
| `All` | A list of objects that map the attributes or field names of your Slack pages and assets to Amazon Q index field names. | `object` This property has the following sub-properties: `indexFieldName`, `indexFieldType`, `dataSourceFieldName`, and `dateFieldFormat`. | Yes |
| `indexFieldName` | The field name of your Slack pages and assets. | `string` | Yes |
| `indexFieldType` | The field type of your Slack pages and assets. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your Slack pages and assets. | `string` | Yes |
| `dateFieldFormat` | The date format of your Slack pages and assets. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/slack-api.html) | Yes |
| `isCrawlAcl` | Specify true to crawl access control information from documents. Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. | `boolean` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| `fieldForUserId` | Specify field to use for UserId for ACL crawling. | `string` | No |
| `inclusionPatterns` | A list of regular expression patterns to include specific content in your Slack data source. Content that matches the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array` | No |
| `exclusionPatterns` | A list of regular expression patterns to exclude specific content in your Slack data source. Content that matches the patterns are excluded from the index. Content that doesn't match the patterns are included in the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array` | No |
| `crawlBotMessages` | `true` to crawl Slack bot messages. | `boolean` | No |
| `excludeArchived` | `true` to exclude archived messages from crawl. | `boolean` | No |
| `conversationType` | The type of conversation that you want to index. | `string` Valid values are `PUBLIC_CHANNEL`, `PRIVATE_CHANNEL`, `GROUP_MESSAGE`, and `DIRECT_MESSAGE`. | No |
| `channelFilter` | The type of channel that you want to index whether private\$1channel or public\$1channel. | `object` This property has the following sub-properties: `private_channel` and `public_channel`. | No |
| `private_channel` | The IDs of the private channel that you want to index. | `array` | No |
| `public_channel` | The IDs of public channel that you want to index. | `array` | No |
| `channelIdFilter` | You can choose to crawl specific channels vy channel ID using the channelIdFilter. | `array` | No |
| `sinceDate` | You can choose to configure a sinceDate parameter so that the Slack connector crawls content based on a specific sinceDate. | `string` Specify the date in the form `^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$` or as an empty string. | No |
| `lookBack` | You can choose to configure a lookBack parameter so that the Slack connector crawls lookBack content. | `string` Specify the value in the form `^[0-9]*$`. | No |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/slack-api.html) | Yes |
| `type` | The type of data source. Specify SLACK as your data source type. | `string` | Yes |
| `enableIdentityCrawler` | Specify true to use the Amazon Q identity crawler to sync identity/principal information on users and groups with access to specific documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). | `boolean` | Yes |
| `secretArn` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Slack. | `string` The secret must contain a JSON structure with the following keys: {
"slackToken": "token"
} | Yes |
| `version` | The version of this template that's currently supported. | `string` | No |
## Slack JSON schema
The following is the Slack JSON schema:
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"pattern": "SLACK"
},
"syncMode": {
"type": "string",
"enum": ["FORCED_FULL_CRAWL", "FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string"
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"teamId": {
"type": "string"
}
},
"required": ["teamId"]
}
}
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"All": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
},
"required": []
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"exclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"crawlBotMessages": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"excludeArchived": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"conversationType": {
"type": "array",
"items": {
"type": "string",
"enum": [
"PUBLIC_CHANNEL",
"PRIVATE_CHANNEL",
"GROUP_MESSAGE",
"DIRECT_MESSAGE"
]
}
},
"channelFilter": {
"type": "object",
"properties": {
"private_channel": {
"type": "array",
"items": {
"type": "string"
}
},
"public_channel": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"channelIdFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"sinceDate": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
},
{
"type": "string",
"pattern": ""
}
]
},
"lookBack": {
"type": "string",
"pattern": "^[0-9]*$"
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"type",
"secretArn",
"syncMode",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
}
```
## Slack JSON schema example
The following is the Slack JSON schema example:
```
{
"type": "SLACK",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-slack-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"teamId": "T12345678"
}
},
"repositoryConfigurations": {
"All": {
"fieldMappings": [
{
"indexFieldName": "message_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"isCrawlAcl": "true",
"maxFileSizeInMegaBytes": "50",
"fieldForUserId": "user_id",
"exclusionPatterns": ["*.tmp"],
"inclusionPatterns": ["*"],
"crawlBotMessages": "false",
"excludeArchived": "true",
"conversationType": ["PUBLIC_CHANNEL", "PRIVATE_CHANNEL"],
"channelFilter": {
"private_channel": ["C12345678"],
"public_channel": ["C87654321"]
},
"channelIdFilter": ["C12345678"],
"sinceDate": "2023-01-01T00:00:00Z",
"lookBack": "7",
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
},
"version": "1.0.0"
}
```
# Connecting Amazon Q Business to Slack using AWS CloudFormation
Using the CloudFormation
You use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html) resource to connect a data source to your Amazon Q application.
Use the [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-qbusiness-datasource.html#cfn-qbusiness-datasource-applicationid) property to provide a JSON or YAML schema with the necessary configuration details specific to your data source connector.
To learn more about AWS CloudFormation, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) in the *CloudFormation User Guide*.
**Topics**
+ [
## Slack configuration properties
](#slack-configuration-keys)
+ [
## Slack JSON schema for using the configuration property with AWS CloudFormation
](#slack-cfn-json)
+ [
## Slack YAML schema for using the configuration property with AWS CloudFormation
](#slack-cfn-yaml)
## Slack configuration properties
The following provides information about important configuration properties required in the schema.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration information for the endpoint for the data source. | `object` This property has the following sub-property: `repositoryEndpointMetadata`. | Yes |
| `repositoryEndpointMetadata` | The endpoint information for the data source. | `object` This property has the following sub-property: `teamId`. | Yes |
| `teamId` | The Slack team ID you copied from your Slack main page URL. | `string` | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` This property has the following sub-property: `All`. | No |
| `All` | A list of objects that map the attributes or field names of your Slack pages and assets to Amazon Q index field names. | `object` This property has the following sub-properties: `indexFieldName`, `indexFieldType`, `dataSourceFieldName`, and `dateFieldFormat`. | Yes |
| `indexFieldName` | The field name of your Slack pages and assets. | `string` | Yes |
| `indexFieldType` | The field type of your Slack pages and assets. | `string` The allowed values are `STRING`, `STRING_LIST`, and `DATE`. | Yes |
| `dataSourceFieldName` | The data source field name of your Slack pages and assets. | `string` | Yes |
| `dateFieldFormat` | The date format of your Slack pages and assets. | `string` Specify the date format in the form `yyyy-MM-dd'T'HH:mm:ss'Z'` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` This property has the following sub-properties. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/slack-cfn.html) | Yes |
| `isCrawlAcl` | Specify true to crawl access control information from documents. Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. | `boolean` | No |
| `maxFileSizeInMegaBytes` | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. | `string` | No |
| `fieldForUserId` | Specify field to use for UserId for ACL crawling. | `string` | No |
| `inclusionPatterns` | A list of regular expression patterns to include specific content in your Slack data source. Content that matches the patterns are included in the index. Content that doesn't match the patterns are excluded from the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array` | No |
| `exclusionPatterns` | A list of regular expression patterns to exclude specific content in your Slack data source. Content that matches the patterns are excluded from the index. Content that doesn't match the patterns are included in the index. If any content matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the content isn't included in the index. | `array` | No |
| `crawlBotMessages` | `true` to crawl Slack bot messages. | `boolean` | No |
| `excludeArchived` | `true` to exclude archived messages from crawl. | `boolean` | No |
| `conversationType` | The type of conversation that you want to index. | `string` Valid values are `PUBLIC_CHANNEL`, `PRIVATE_CHANNEL`, `GROUP_MESSAGE`, and `DIRECT_MESSAGE`. | No |
| `channelFilter` | The type of channel that you want to index whether private\$1channel or public\$1channel. | `object` This property has the following sub-properties: `private_channel` and `public_channel`. | No |
| `private_channel` | The IDs of the private channel that you want to index. | `array` | No |
| `public_channel` | The IDs of public channel that you want to index. | `array` | No |
| `channelIdFilter` | You can choose to crawl specific channels vy channel ID using the channelIdFilter. | `array` | No |
| `sinceDate` | You can choose to configure a sinceDate parameter so that the Slack connector crawls content based on a specific sinceDate. | `string` Specify the date in the form `^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$` or as an empty string. | No |
| `lookBack` | You can choose to configure a lookBack parameter so that the Slack connector crawls lookBack content. | `string` Specify the value in the form `^[0-9]*$`. | No |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/slack-cfn.html) | Yes |
| `type` | The type of data source. Specify SLACK as your data source type. | `string` | Yes |
| `enableIdentityCrawler` | Specify true to use the Amazon Q identity crawler to sync identity/principal information on users and groups with access to specific documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). | `boolean` | Yes |
| `secretArn` | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Slack. | `string` The secret must contain a JSON structure with the following keys: {
"slackToken": "token"
} | Yes |
| `version` | The version of this template that's currently supported. | `string` | No |
## Slack JSON schema for using the configuration property with AWS CloudFormation
Slack JSON schema
The following is the Slack JSON schema and examples for the configuration property for AWS CloudFormation.
**Topics**
+ [
### Slack JSON schema for using the configuration property with AWS CloudFormation
](#slack-cfn-json-schema)
+ [
### Slack JSON schema example for using the configuration property with AWS CloudFormation
](#slack-cfn-json-example)
### Slack JSON schema for using the configuration property with AWS CloudFormation
Slack JSON schema
The following is the Slack JSON schema for the configuration property for CloudFormation
```
{
"type": "object",
"properties": {
"type": {
"type": "string",
"pattern": "SLACK"
},
"syncMode": {
"type": "string",
"enum": ["FORCED_FULL_CRAWL", "FULL_CRAWL", "CHANGE_LOG"]
},
"secretArn": {
"type": "string"
},
"enableIdentityCrawler": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"teamId": {
"type": "string"
}
},
"required": ["teamId"]
}
}
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"All": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "DATE", "LONG"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": ["fieldMappings"]
}
},
"required": []
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"exclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionPatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"crawlBotMessages": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"excludeArchived": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
]
},
"conversationType": {
"type": "array",
"items": {
"type": "string",
"enum": [
"PUBLIC_CHANNEL",
"PRIVATE_CHANNEL",
"GROUP_MESSAGE",
"DIRECT_MESSAGE"
]
}
},
"channelFilter": {
"type": "object",
"properties": {
"private_channel": {
"type": "array",
"items": {
"type": "string"
}
},
"public_channel": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"channelIdFilter": {
"type": "array",
"items": {
"type": "string"
}
},
"sinceDate": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
},
{
"type": "string",
"pattern": ""
}
]
},
"lookBack": {
"type": "string",
"pattern": "^[0-9]*$"
},
"enableDeletionProtection": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"enum": ["true", "false"]
}
],
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"required": []
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"required": [
"type",
"secretArn",
"syncMode",
"enableIdentityCrawler",
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties"
]
}
}
```
### Slack JSON schema example for using the configuration property with AWS CloudFormation
Slack JSON schema example
The following is the Slack JSON schema example for the configuration property for CloudFormation
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Description": "CloudFormation SLACK Data Source Template",
"Resources": {
"DataSourceSlack": {
"Type": "AWS::QBusiness::DataSource",
"Properties": {
"ApplicationId": "app12345-1234-1234-1234-123456789012",
"IndexId": "indx1234-1234-1234-1234-123456789012",
"DisplayName": "MySlackDataSource",
"RoleArn": "arn:aws:iam::123456789012:role/qbusiness-data-source-role",
"Configuration": {
"type": "SLACK",
"syncMode": "FULL_CRAWL",
"secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-slack-secret",
"enableIdentityCrawler": "true",
"connectionConfiguration": {
"repositoryEndpointMetadata": {
"teamId": "T12345678"
}
},
"repositoryConfigurations": {
"All": {
"fieldMappings": [
{
"indexFieldName": "message_id",
"indexFieldType": "STRING",
"dataSourceFieldName": "id",
"dateFieldFormat": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
]
}
},
"additionalProperties": {
"isCrawlAcl": "true",
"maxFileSizeInMegaBytes": "50",
"fieldForUserId": "user_id",
"exclusionPatterns": ["*.tmp"],
"inclusionPatterns": ["*"],
"crawlBotMessages": "false",
"excludeArchived": "true",
"conversationType": ["PUBLIC_CHANNEL", "PRIVATE_CHANNEL"],
"channelFilter": {
"private_channel": ["C12345678"],
"public_channel": ["C87654321"]
},
"channelIdFilter": ["C12345678"],
"sinceDate": "2023-01-01T00:00:00Z",
"lookBack": "7",
"enableDeletionProtection": "false",
"deletionProtectionThreshold": "15"
}
}
}
}
}
}
```
## Slack YAML schema for using the configuration property with AWS CloudFormation
Slack YAML schema
The following is the Slack YAML schema and examples for the configuration property for AWS CloudFormation:
**Topics**
+ [
### Slack YAML schema for using the configuration property with AWS CloudFormation
](#slack-cfn-yaml-schema)
+ [
### Slack YAML schema example for using the configuration property with AWS CloudFormation
](#slack-cfn-yaml-example)
### Slack YAML schema for using the configuration property with AWS CloudFormation
Slack YAML schema
The following is the Slack YAML schema for the configuration property for CloudFormation.
```
type: object
properties:
type:
type: string
pattern: SLACK
syncMode:
type: string
enum:
- FORCED_FULL_CRAWL
- FULL_CRAWL
- CHANGE_LOG
secretArn:
type: string
enableIdentityCrawler:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
connectionConfiguration:
type: object
properties:
repositoryEndpointMetadata:
type: object
properties:
teamId:
type: string
required:
- teamId
repositoryConfigurations:
type: object
properties:
All:
type: object
properties:
fieldMappings:
type: array
items:
type: object
properties:
indexFieldName:
type: string
indexFieldType:
type: string
enum:
- STRING
- STRING_LIST
- DATE
- LONG
dataSourceFieldName:
type: string
dateFieldFormat:
type: string
pattern: "yyyy-MM-dd'T'HH:mm:ss'Z'"
required:
- indexFieldName
- indexFieldType
- dataSourceFieldName
required:
- fieldMappings
additionalProperties:
type: object
properties:
isCrawlAcl:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
maxFileSizeInMegaBytes:
type: string
fieldForUserId:
type: string
exclusionPatterns:
type: array
items:
type: string
inclusionPatterns:
type: array
items:
type: string
crawlBotMessages:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
excludeArchived:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
conversationType:
type: array
items:
type: string
enum:
- PUBLIC_CHANNEL
- PRIVATE_CHANNEL
- GROUP_MESSAGE
- DIRECT_MESSAGE
channelFilter:
type: object
properties:
private_channel:
type: array
items:
type: string
public_channel:
type: array
items:
type: string
channelIdFilter:
type: array
items:
type: string
sinceDate:
anyOf:
- type: string
pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
- type: string
pattern: ""
lookBack:
type: string
pattern: "^[0-9]*$"
enableDeletionProtection:
anyOf:
- type: boolean
- type: string
enum:
- true
- false
default: false
deletionProtectionThreshold:
type: string
default: "15"
required: []
version:
type: string
anyOf:
- pattern: 1.0.0
required:
- type
- secretArn
- syncMode
- enableIdentityCrawler
- connectionConfiguration
- repositoryConfigurations
- additionalProperties
```
### Slack YAML schema example for using the configuration property with AWS CloudFormation
Slack JSON schema example
The following is the Slack YAML example for the Configuration property for CloudFormation:
```
AWSTemplateFormatVersion: "2010-09-09"
Description: CloudFormation SLACK Data Source Template
Resources:
DataSourceSlack:
Type: AWS::QBusiness::DataSource
Properties:
ApplicationId: app12345-1234-1234-1234-123456789012
IndexId: indx1234-1234-1234-1234-123456789012
DisplayName: MySlackDataSource
RoleArn: arn:aws:iam::123456789012:role/qbusiness-data-source-role
Configuration:
type: SLACK
syncMode: FULL_CRAWL
secretArn: arn:aws:secretsmanager:us-west-2:123456789012:secret:my-slack-secret
enableIdentityCrawler: "true"
connectionConfiguration:
repositoryEndpointMetadata:
teamId: T12345678
repositoryConfigurations:
All:
fieldMappings:
- indexFieldName: message_id
indexFieldType: STRING
dataSourceFieldName: id
dateFieldFormat: yyyy-MM-dd'T'HH:mm:ss'Z'
additionalProperties:
isCrawlAcl: "true"
maxFileSizeInMegaBytes: "50"
fieldForUserId: user_id
exclusionPatterns:
- "*.tmp"
inclusionPatterns:
- "*"
crawlBotMessages: "false"
excludeArchived: "true"
conversationType:
- PUBLIC_CHANNEL
- PRIVATE_CHANNEL
channelFilter:
private_channel:
- C12345678
public_channel:
- C87654321
channelIdFilter:
- C12345678
sinceDate: "2023-01-01T00:00:00Z"
lookBack: "7"
enableDeletionProtection: "false"
deletionProtectionThreshold: "15"
```
# How Amazon Q Business connector crawls Slack ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
Slack organizes content into documents, which include messages, attachments, posts, snippets, thread replies, and emojis. Messages and attachments can belong to different conversation types such as direct messages (DMs), public channels, or private channels.
When you connect a Slack data source to Amazon Q Business, Amazon Q Business crawls ACL information (channel IDs) attached to a document from your Slack instance. If you choose to activate ACL crawling, this information can be used to filter chat responses to your end user's document access level. Access Control (ACLs) in Slack is managed through users and groups.
**Identity Crawling**: Slack allows link sharing at the document level. If a document link is shared across different channels (DMs, groups, or private channels), the new channel ID is included during crawling, effectively expanding ACLs to include members of those channels. Slack does not enforce explicit deny rules: public channels allow user removal but do not prevent them from rejoining, whereas private channels restrict reentry without an invitation. The minimum permission to query channel data varies: for public channels, workspace membership is sufficient, while private channels require direct membership for access. Slack enforces username restrictions, supporting only lowercase letters, numbers, periods, hyphens, and underscores. This lowercase format is maintained when crawling identities. ACL mismatches can occur if case differences exist between Slack usernames and identity data stored in the connector, potentially preventing access to crawled information. When a user is deactivated or deleted, they lose access to crawled data, and subsequent syncs reflect this by removing the user from ACLs.
**Permission Inheritance**: The Slack Workspace is the top-most entity controlling access. All workspace members can access public channels by default. Public channels have no ACLs; they are accessible to all workspace members. If ACLs are disabled, all public channel content is open to everyone on Amazon Q. DMs, groups, and private channels have independent ACLs, which completely replace any parent ACLs. Private channels restrict access to invited members, including external collaborators via Slack Connect. All entities inherit permissions from the parent.
**Mapping Rules**: Slack's inheritance mapping follows its native structure without custom logic. Federated groups are treated as local upon syncing, with all members stored regardless of status. Emails, links, and other text within messages are crawled as regular strings without specific parsing. Link-sharing does not modify document ACLs: a shared link in a message is crawled as plain text rather than as an access control change. Public channels are accessible to all Amazon Q users if no ACL is applied.
**Failure handling**: The connector follows a fail-close approach, meaning if there are permission-related issues or API failures, affected documents are skipped from ingestion rather than being made publicly accessible. This prevents unauthorized access while maintaining data integrity.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Slack data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Slack connector supports the following field mappings:
| Slack field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| size | sl\$1gen\$1size | Custom | Long (numeric) |
| emojis | sl\$1gen\$1emojis | Custom | String list |
| title | sl\$1gen\$1title | Custom | String |
| authors | \$1authors | Default | String list |
| url | \$1source\$1uri | Default | String |
| category | sl\$1gen\$1category | Custom | String |
| created\$1at | \$1created\$1at | Default | Date |
| last\$1updated\$1at | \$1last\$1updated\$1at | Default | Date |
| msg\$1channel\$1id | sl\$1message\$1channel\$1id | Custom | String |
| msg\$1channel\$1name | sl\$1msg\$1channel\$1name | Custom | String |
# IAM role for the Slack connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Smartsheet to Amazon Q Business
Smartsheet
Smartsheet is an enterprise work management platform that lets users manage projects, programs and processes at scale using sheets, channels, and workspaces. You can connect your Smartsheet instance to Amazon Q Business—using either the AWS Management Console, CLI, or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q Business web experience.
Integrating Smartsheet as a data source in Amazon Q Business enables users to quickly get insights from project sheets. For example, users can ask questions like:
+ "Which project manager is responsible for Project Harpo?", where the answer comes from a Smartsheet row
+ "What are the requirements for the Create APIs task?", where the answer is fetched from a PDF attached to the row for Create APIs
+ "Who is the owner of the Individual Task Management workspace?", where the answer comes from workspace metadata
With the Amazon Q Business Smartsheet connector, you can solve the following kinds of use cases.
+ **Project status updates** – Get quick insights into project health without having to open Smartsheet with questions like:
+ "What's the status of the website redesign project?"
+ "Is the mobile app launch on track for the planned date?"
+ "Which projects are currently behind schedule in the Q3 Roadmap sheet?"
+ **Task management** – Find information about tasks and action items with questions like:
+ "What tasks are assigned to Mary Major?"
+ "Has the marketing plan document been completed?"
+ "What's the due date for the customer research presentation?"
The Amazon Q Business Smartsheet connector understands user access permissions and strictly enforces them at the time of the query. This ensures that users aren't able to see content they don't have access to.
**Note**
We recommend enabling [Cross-region inference for Amazon Q Business](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/cross-region-inference.html) for your Amazon Q Business application connector to get the best customer experience with improved query response accuracy.
**Topics**
+ [
# Known limitations for the Smartsheet connector
](smartsheet-limitations.md)
+ [
# Prerequisites for connecting Amazon Q Business to Smartsheet
](smartsheet-prereqs.md)
+ [
# Connecting Amazon Q Business to Smartsheet using the console
](smartsheet-console.md)
+ [
# Connecting Amazon Q Business to Smartsheet using APIs
](smartsheet-api.md)
+ [
# How Amazon Q Business connector crawls Smartsheet ACLs
](smartsheet-user-management.md)
+ [
# IAM role for Smartsheet connector
](smartsheet-iam-role.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Smartsheet connector
Known limitations
The Smartsheet connector has the following known limitations:
+ If you remove users’ access to a Smartsheet data source but not to Amazon Q Business, they will be able to receive responses from the data source when they query Amazon Q Business.
+ The Smartsheet connector will provide responses from the most applicable single sheet. That is, it will search across all sheets and find the sheet with the most relevant answer and provide that instead of aggregating data across multiple sheets. For example, it can't answer questions like: "Show me tasks that are past due across all my sheets."
+ For hierarchical sheets, Amazon Q Business accuracy can drop when queries are directly related to the hierarchical structure.
For example, if a sheet has hierarchical structure about high-level tasks and its subtasks, and a user asks "What's the amount of time needed to finish all tasks?" then Amazon Q Business might add up all times assigned to both high-level tasks and the sub-tasks. This calculation is wrong as the amount of time to finish the high-level task is just a sum up of the sub-tasks.
However, if the user asks a query such as "How many tasks are assigned to Mary Major?", they would get an accurate response.
+ For sheets with similar names—(for example, “Blockchain Integration - Project Plan” and “Blockchain Integration - Impact Tracker”)—if a query mentions just “Blockchain Integration” then you might not get an accurate response. To get accurate responses, we recommend:
+ providing clearer titles/descriptions of the sheets, or
+ providing more detailed questions to reduce ambiguity.
# Prerequisites for connecting Amazon Q Business to Smartsheet
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
+ **In Smartsheet, make sure you have:**
+ Access to the Smartsheet Event Reporting API. Use the [Events API Access Request](https://app.smartsheet.com/b/form/5db2cf1b981f445cabaa22d9421cc19d) form to request access for your organization.
+ An Smartsheet system admin user or a licensed user for Smartsheet who can generate an access token. With this access token, your connector will have access to crawl all sheets and workspaces created by or shared with this user.
+ A Smartsheet access token. You need this to connect Smartsheet to Amazon Q Business. For information on how to generate this token in Smartsheet, see [Authentication and Access Tokens](https://smartsheet.redoc.ly/#section/API-Basics/Authentication-and-Access-Tokens) in the *Smartsheet API Reference*.
+ **In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Smartsheet authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Connecting Amazon Q Business to Smartsheet using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Smartsheet using the AWS Management Console.
**Note**
Before you begin adding your data source, make sure you've created an Amazon Q Business application, and added an index and retriever to it.
**Connecting Amazon Q to Smartsheet**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Smartsheet** data source to your Amazon Q application.
1. Then, on the **Smartsheet** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. In **User type** – Choose the user type in your Smartsheet account. You can choose between **System Admin** and **Non-System Admin**. System Admins can ingest sheets, folders, and workspaces into Amazon Q Business. Non-System Admins can ingest only sheets.
1. **Authentication** – Enter the following information for your **AWS Secrets Manager secret**.
1. **Secret name** – A name for your secret.
1. For **Smartsheet API access token** – Enter the value for the access token you created in your Smartsheet account.
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/smartsheet-connector.html#smartsheet-iam).
1. In **Sync scope**, enter the following information:
1. In **Select specific sheets, folders, and workspaces**, for **ID type** – Select content to sync using a specific **Sheet ID**, **Folder ID**, and **Workspace ID**.
1. For **Select attachments and conversations**, select from the following options:
+ **All attachments** – Select to include all attachments.
+ **All conversations** – Select to include all conversations.
1. In **Additional configuration – *optional*, select from the following options:**
+ **Sheet and folder regex patterns** – Choose to include or exclude specific sheet and folder names using regex patterns.
+ **Attachment regex patterns** – Choose to include or exclude specific files by name and type using regex patterns.
1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB.
1. **Multi-media content configuration – optional** – To enable content extraction from embedded images and visuals in documents, choose **Visual content in documents**.
To extract audio transcriptions and video content, enable processing for the following file types:
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. For **Sync mode**, choose how you want to update your index when your data source content changes. When you sync your data source with Amazon Q for the first time, all content is synced by default.
+ **Full sync**—Sync all content regardless of the previous sync status.
+ **New, modified, or deleted content sync**—Sync only new, modified, and deleted documents.
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run).
**Note**
The Amazon Q Business Smartsheet connector doesn't support hourly syncs. For optimal performance, choose to sync your data during a time window outside of 11am UTC to 11pm UTC.
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields. Add the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Smartsheet using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
## JSON schema
The following is the Smartsheet JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"authType": {
"type": "string",
"enum": [
"APIToken"
]
}
},
"required": [
"authType"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"sheet": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE",
"STRING_LIST",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
},
"sheetAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE",
"STRING_LIST",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
},
"sheetConversation": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE",
"STRING_LIST",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
},
"sheetConversationAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE",
"STRING_LIST",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
},
"rowAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE",
"STRING_LIST",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
},
"rowConversation": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE",
"STRING_LIST",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
},
"rowConversationAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": [
"STRING",
"DATE",
"STRING_LIST",
"LONG"
]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "yyyy-MM-dd'T'HH:mm:ss'Z'"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
},
"required": [
"fieldMappings"
]
}
}
},
"additionalProperties": {
"type": "object",
"properties": {
"workspaceIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 20
},
"sheetIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 20
},
"folderIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 20
},
"fieldForUserId": {
"type": "string"
},
"userType": {
"type": "string"
},
"isCrawlAcl": {
"type": "boolean"
},
"isCrawlSheets": {
"type": "boolean"
},
"isCrawlSheetAttachments": {
"type": "boolean"
},
"isCrawlSheetConversations": {
"type": "boolean"
},
"isCrawlSheetConversationAttachments": {
"type": "boolean"
},
"isCrawlRows": {
"type": "boolean"
},
"isCrawlRowAttachments": {
"type": "boolean"
},
"isCrawlRowConversations": {
"type": "boolean"
},
"isCrawlRowConversationAttachments": {
"type": "boolean"
},
"isCrawlRowProofs": {
"type": "boolean"
},
"isMetadataAppended": {
"type": "boolean"
},
"isConversationAppended": {
"type": "boolean"
},
"inclusionAttachmentTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionAttachmentTypePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionAttachmentNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionAttachmentNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionFolderNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionFolderNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"inclusionSheetNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"exclusionSheetNamePatterns": {
"type": "array",
"items": {
"type": "string"
}
},
"enableDeletionProtection": {
"type": "boolean",
"default": false
},
"deletionProtectionThreshold": {
"type": "string",
"default": "15"
}
},
"not": {
"properties": {
"workspaceIds": { "maxItems": 0 },
"sheetIds": { "maxItems": 0 },
"folderIds": { "maxItems": 0 }
}
}
},
"enableIdentityCrawler": {
"type": "boolean"
},
"syncMode": {
"type": "string",
"enum": [
"FULL_CRAWL",
"FORCED_FULL_CRAWL",
"CHANGE_LOG"
]
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"type": {
"type": "string",
"pattern": "SMARTSHEET"
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
}
},
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"syncMode",
"additionalProperties",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description | Type | Required |
| --- | --- | --- | --- |
| `connectionConfiguration` | Configuration details for connecting to the data source. | `object` | Yes |
| `connectionConfiguration.repositoryEndpointMetadata` | Metadata for the repository endpoint. | `object` | Yes |
| `connectionConfiguration.repositoryEndpointMetadata.authType` | The authentication type. | `string` The only allowed value is: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/smartsheet-api.html) | Yes |
| `repositoryConfigurations` | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. | `object` | Yes |
| `repositoryConfigurations.sheet` | Configuration for Smartsheet sheets. | `object` | No |
| `repositoryConfigurations.sheet.fieldMappings` | Field mappings for Smartsheet sheets. | `array` of `object` | Yes (if sheet is present) |
| `repositoryConfigurations.sheetAttachment` | Configuration for Smartsheet sheet attachments. | `object` | No |
| `repositoryConfigurations.sheetConversation` | Configuration for Smartsheet sheet conversations. | `object` | No |
| `repositoryConfigurations.sheetConversationAttachment` | Configuration for Smartsheet sheet conversation attachments. | `object` | No |
| `repositoryConfigurations.row` | Configuration for Smartsheet rows. | `object` | No |
| `repositoryConfigurations.rowAttachment` | Configuration for row attachments. | `object` | No |
| `repositoryConfigurations.rowConversation` | Configuration for Smartsheet row conversations. | `object` | No |
| `repositoryConfigurations.rowConversationAttachment` | Configuration for Smartsheet row conversation attachments. | `object` | No |
| `repositoryConfigurations.proofAttachment` | Configuration for Smartsheet proof attachments. | `object` | No |
| `repositoryConfigurations.proofConversation` | Configuration for Smartsheet proof conversations. | `object` | No |
| `repositoryConfigurations.proofConversationAttachment` | Configuration for Smartsheet proof conversation attachments. | `object` | No |
| `additionalProperties` | Additional configuration options for your content in your data source. | `object` | Yes |
| `additionalProperties.workspaceIds` | List of Smartsheet workspace IDs to crawl. | `array` of `string` | No |
| `additionalProperties.sheetIds` | List of Smartsheet sheet IDs to crawl. | `array` of `string` | No |
| `additionalProperties.folderIds` | List of Smartsheet folder IDs to crawl. | `array` of `string` | No |
| `additionalProperties.fieldForUserId` | Field for user ID. | `string` | No |
| `additionalProperties.userType` | User type. | `string` | Yes |
| `additionalProperties.isCrawlAcl` | Whether to crawl ACL. | `boolean` | No |
| `additionalProperties.isCrawlSheets` | Whether to crawl Smartsheet sheets. | `boolean` | No |
| `additionalProperties.isCrawlSheetAttachments` | Whether to crawl Smartsheet sheet attachments. | `boolean` | No |
| `additionalProperties.isCrawlSheetConversations` | Whether to crawl Smartsheet sheet conversations. | `boolean` | No |
| `additionalProperties.isCrawlSheetConversationAttachments` | Whether to crawl Smartsheet sheet conversation attachments. | `boolean` | No |
| `additionalProperties.isCrawlRows` | Whether to crawl Smartsheet rows. | `boolean` | No |
| `additionalProperties.isCrawlRowAttachments` | Whether to crawl Smartsheet row attachments. | `boolean` | No |
| `additionalProperties.isCrawlRowConversations` | Whether to crawl Smartsheet row conversations. | `boolean` | No |
| `additionalProperties.isCrawlRowConversationAttachments` | Whether to crawl Smartsheet row conversation attachments. | `boolean` | No |
| `additionalProperties.isCrawlRowProofs` | Whether to crawl Smartsheet row proofs. | `boolean` | No |
| `additionalProperties.isMetadataAppended` | Whether to append Smartsheet metadata. | `boolean` | No |
| `additionalProperties.isConversationAppended` | Whether to append Smartsheet conversations. | `boolean` | No |
| `additionalProperties.inclusionAttachmentTypePatterns` | Patterns for including Smartsheet attachment types. | `array` of `string` | No |
| `additionalProperties.exclusionAttachmentTypePatterns` | Patterns for excluding Smartsheet attachment types. | `array` of `string` | No |
| `additionalProperties.inclusionAttachmentNamePatterns` | Patterns for including Smartsheet attachment names. | `array` of `string` | No |
| `additionalProperties.exclusionAttachmentNamePatterns` | Patterns for excluding Smartsheet attachment names. | `array` of `string` | No |
| `additionalProperties.inclusionFolderNamePatterns` | Patterns for including Smartsheet folder names. | `array` of `string` | No |
| `additionalProperties.exclusionFolderNamePatterns` | Patterns for excluding Smartsheet folder names. | `array` of `string` | No |
| `additionalProperties.inclusionSheetNamePatterns` | Patterns for including Smartsheet sheet names. | `array` of `string` | No |
| `additionalProperties.exclusionSheetNamePatterns` | Patterns for excluding Smartsheet sheet names. | `array` of `string` | No |
| `additionalProperties.enableDeletionProtection` | Whether to enable deletion protection. To learn more, see [Document deletion safeguard](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#document-deletion-safeguard). | `boolean` | No |
| `additionalProperties.deletionProtectionThreshold` | Threshold for deletion protection. To learn more, see [Document deletion safeguard](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#document-deletion-safeguard) | `string` | No |
| `enableIdentityCrawler` | Whether to enable the identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to certain documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). | `boolean` | No |
| `syncMode` | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. | `string` The allowed values are: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/smartsheet-api.html) | Yes |
| `secretArn` | The ARN of the secret containing the Smartsheet credentials required to connect Amazon Q Business to Smartsheet. | `string` The minimum length is 20 and the maximum length is 2,048 characters. | Yes |
| `type` | The type of the data source. | `string` The only allowed value is: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/smartsheet-api.html) | Yes |
| `version` | The version of the template that's currently supported. | `string` Must match the pattern "1.0.0". | No |
# How Amazon Q Business connector crawls Smartsheet ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
Smartsheet organizes its data into several entities, including Workspaces, Sheets, Rows, Columns, Attachments, and Comments. Workspaces serve as hierarchical containers that hold folders and individual sheets. Connectors support crawling ACL and identity information where applicable based on the data source. When you connect a Smartsheet data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your Smartsheet instance. The Smartsheet connector does not allow disabling ACLs, so you must always inforce permissions. ACL information can be used to filter chat responses based your end users' document access level.
**Roles/Permissions**: Users and groups can be assigned various roles including Admin, Editor, and Viewer. Permissions can be managed at different levels, including Workspaces, Sheets, and individual Rows. Smartsheet enforces an Allow Mode for ACLs, meaning permissions are granted explicitly without an explicit deny option. Sheets and Workspaces can be shared via links with different permission levels (View or Edit), but public link sharing is not supported. In addition, Smartsheet allows setting sheets as either searchable or non-searchable, and the connector ensures that this setting is honored when ingesting Smartsheet data. The minimum permission required to read a sheet or workspace is "Viewer". Proper mapping between Smartsheet ACLs and Amazon Q ACL definitions is essential to ensure security and permission consistency.
**Identity Crawling**: Smartsheet supports both local and federated users/groups, but the connector does not support federated. Usernames in Smartsheet are case-insensitive and allow special characters. This system ensures that two users can have the same name but must have unique email addresses. In addition, group names must be unique, because Smartsheet does not allow duplicate group names with mixed case. This prevents identity collisions, ensuring that permissions and access remain properly assigned. If an identity is deleted and later recreated, it does not automatically inherit previous permissions. Smartsheet does not have a suspended user concept, if a user is removed from the user library, they still appear in shared lists for sheets where they previously had access.
**Permission Inheritance**: Permissions in Smartsheet follow an inheritance model, where Workspaces act as the top-most entity. If no explicit ACL is set at the sheet or folder level, permissions are inherited from the parent Workspace. Inherited permissions typically operate as an intersection of parent permissions, unless explicitly modified. However, sheets can have their own ACLs that override inherited permissions. Document-level permissions can include options such as "View Sheet" or "Edit Sheet".
**Change Management**: Change Log Mode in Amazon Q Business enables incremental updates by capturing modifications made to content in Smartsheet. It indexes only newly added, updated, or deleted items since the last crawl, onstead of re-indexing all documents. Any changes to user or group access permissions are also recorded, ensuring accurate and up-to-date indexing.
**Failure handling**: The connector follows a fail-close approach, meaning if there are permission-related issues or API failures, affected documents are skipped from ingestion rather than being made publicly accessible. This prevents unauthorized access while maintaining data integrity.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# IAM role for Smartsheet connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowsAmazonQToGetS3Objects",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::bucket/*"
],
"Effect": "Allow",
"Condition": {
"StringEquals": {
"aws:ResourceAccount": "111122223333"
}
}
},
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:us-west-2:111122223333:secret:QBusiness-Smartsheet-Example-Secret"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:us-west-2:111122223333:key/wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": "arn:aws:qbusiness:us-west-2:111122223333:application/312ba974-4afc-8b7a-3180-6aec1db0d57c/index/e2a71750-c4fd0-b34a-bf23-ddcce192d11d"
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:us-west-2:111122223333:application/312ba974-4afc-8b7a-3180-6aec1db0d57c",
"arn:aws:qbusiness:us-west-2:111122223333:application/312ba974-4afc-8b7a-3180-6aec1db0d57c/index/e2a71750-c4fd0-b34a-bf23-ddcce192d11d",
"arn:aws:qbusiness:us-west-2:111122223333:application/312ba974-4afc-8b7a-3180-6aec1db0d57c/index/e2a71750-bf23-4fd0-b34a-192d11dddcce/data-source/*"
]
}
]
}
```
------
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:us-east-1:111122223333:application/application-id"
}
}
}
]
}
```
------
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Connecting Zendesk to Amazon Q Business
Zendesk
Zendesk is a customer relationship management system that helps businesses automate and enhance customer support interactions. You can connect a Zendesk instance to Amazon Q Business—using either the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) API—and create an Amazon Q web experience.
**Topics**
+ [
# Known limitations for the Zendesk connector
](zendesk-limitations.md)
+ [
# Zendesk connector overview
](zendesk-overview.md)
+ [
# Prerequisites for connecting Amazon Q Business to Zendesk
](zendesk-prereqs.md)
+ [
# Setting up Zendesk for connecting to Amazon Q Business
](zendesk-credentials.md)
+ [
# Connecting Amazon Q Business to Zendesk using the console
](zendesk-console.md)
+ [
# Connecting Amazon Q Business to Zendesk using APIs
](zendesk-api.md)
+ [
# How Amazon Q Business connector crawls Zendesk ACLs
](zendesk-user-management.md)
+ [
# Zendesk data source connector field mappings
](zendesk-field-mappings.md)
+ [
# IAM role for the Zendesk connector
](zendesk-iam-role.md)
+ [
# Understand error codes in the Zendesk connector
](zendesk-error-codes.md)
**Learn more**
+ For an overview of the Amazon Q web experience creation process using IAM Identity Center, see [Configuring an application using IAM Identity Center](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application.html).
+ For an overview of the Amazon Q web experience creation process using AWS Identity and Access Management, see [Configuring an application using IAM](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/create-application-iam.html).
+ For an overview of connector features, see [Data source connector concepts](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html).
+ For information about connector configuration best practices, see [Connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Known limitations for the Zendesk connector
Known limitations
The Zendesk connector has the following known limitations:
+ Deleted and archived articles and their comments and attachments aren't supported in **Change log** mode since there are no SDK methods/REST API available for fetching deleted or archived articles.
+ Archived articles aren't supported in **Full Crawl** mode since there are no SDK methods/REST API available for fetching archived articles.
+ Deleted community topics, community posts, and their comments are not supported in **Change Log** mode since there are no SDK methods/REST API available for fetching deleted topics, deleted posts, and their comments.
+ The Zendesk connector can't fetch community topics (added, edited, or deleted), and community posts and their comments (added, edited, or deleted) based on timestamps in **Change log** mode.
+ When Access Control Lists (ACLs) are enabled, the "Sync only new or modified content" option is not available due to Zendesk API limitations. We recommend using "Full sync" or "New, modified, or deleted content sync" modes instead, or disable ACLs if you need to use this sync mode.
# Zendesk connector overview
Overview
The following table gives an overview of the Zendesk connector and its supported features.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/zendesk-overview.html)
# Prerequisites for connecting Amazon Q Business to Zendesk
Prerequisites
Before you begin, make sure that you have completed the following prerequisites.
**In Zendesk, make sure you have:**
+ Created a Zendesk Suite (Professional/Enterprise) administrative account.
+ Copied your Zendesk host URL. For example, *https://\$1sub-domain\$1.zendesk.com/*. You need this URL to allow Amazon Q to connect with your Zendesk data source.
+ Generated Zendesk OAuth 2.0 with implicit grant credentials containing an implicit grant token.
+ Generated Zendesk OAuth 2.0 credentials containing a client ID, client secret, username, and password. You need these credentials to authenticate Amazon Q to access Zendesk.
**In your AWS account, make sure you have:**
+ Created a Amazon Q Business application.
+ Created a [Amazon Q Business retriever and added an index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html).
+ Created an [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds) for your data source and, if using the Amazon Q API, noted the ARN of the IAM role.
+ Stored your Zendesk authentication credentials in an AWS Secrets Manager secret and, if using the Amazon Q API, noted the ARN of the secret.
**Note**
If you’re a console user, you can create the IAM role and Secrets Manager secret as part of configuring your Amazon Q application on the console.
For a list of things to consider while configuring your data source, see [ Data source connector configuration best practices](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-best-practices.html).
# Setting up Zendesk for connecting to Amazon Q Business
Setting up Zendesk
Before you connect Zendesk to Amazon Q Business, you need to create and retrieve the Zendesk credentials you will use to connect Zendesk to Amazon Q. You will also need to add any authorization permissions needed by Zendesk to connect to Amazon Q.
The following procedure gives you an overview of how to configure Zendesk for Amazon Q.
**Configuring Zendesk for OAuth 2.0 authentication**
1. Log in to your Zendesk account. Note the username and password you logged in with. You will need them later to connect to Amazon Q.
1. Copy your Zendesk URL, if you haven't already, from the Zendesk webpage URL. This will be the URL you will input as host URL in Amazon Q.
**Note**
You can also copy your Zendesk host URL from the top menu in the **Admin Center**.
1. From the left navigation menu, choose the settings icon. Then, choose **Go to Admin Center**.
![\[Screenshot of the Zendesk admin interface showing the profile menu where users can access the Admin Center.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/zendesk-1.png)
1. In **Admin Center**, from the left navigation menu, under **Apps and integrations**, choose **Zendesk API**.
![\[Screenshot of the Zendesk Admin Center showing the left navigation menu with the "Zendesk API" option under "Apps and integrations" section.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/zendesk-2.png)
1. From the **Zendesk API** menu, choose **OAuth Clients** and then choose **Add OAuth client**.
![\[Screenshot of the Zendesk API menu showing the "OAuth Clients" option and the "Add OAuth client" button for creating a new OAuth client.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/zendesk-3.png)
1. On the **OAuth Clients** page, under **Create a new OAuth client** enter the following information:
+ **Client name** – A human-readable name for your client. This will be visible to users.
+ **Unique identifier** – An internal code-level identifier for your client. This will be the Client ID you input in Amazon Q.
Optionally, choose to fill in other information based on your use case. Then, choose **Save**.
![\[Screenshot of the Zendesk "Create a new OAuth client" form where users enter client name, redirect URL, and other configuration details for the OAuth client.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/zendesk-4.png)
1. On the **Please store the secret that will appear** dialog box that appears, select **OK**. Then, copy the secret you see into a text editor of your choice and save it. You won't be able to re-generate this secret so it's important that you store it securely. You will input this as the client secret during the connection configuration process in Amazon Q.
![\[Screenshot of the Zendesk client secret dialog box showing the generated secret that needs to be copied and stored securely for API authentication.\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/images/zendesk-5.png)
You now have the username, password, host URL, client ID, and client secret you need to connect Zendesk to Amazon Q.
# Connecting Amazon Q Business to Zendesk using the console
Using the console
The following procedure outlines how to connect Amazon Q Business to Zendesk using the AWS Management Console.
**Connecting Amazon Q to Zendesk**
1. Sign in to the AWS Management Console and open the Amazon Q Business console.
1. From the left navigation menu, choose **Data sources**.
1. From the **Data sources** page, choose **Add data source**.
1. Then, on the **Add data sources** page, from **Data sources**, add the **Zendesk** data source to your Amazon Q application.
1. Then, on the **Zendesk** data source page, enter the following information:
1. **Name and description**, do the following:
+ For **Data source name** – Name your data source for easy tracking.
**Note**
You can include hyphens (-) but not spaces. Maximum of 1,000 alphanumeric characters.
+ **Description – *optional*** – Add an optional description for your data source. This text is viewed only by Amazon Q Business administrators and can be edited later.
1. **Source** – Enter your ** Zendesk URL**. For example, *https://\$1sub-domain\$1.zendesk.com/*.
1. **Authorization** – Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. If supported for your connector, you can manage ACLs by selecting ** Enable ACLs ** to enable ACLs or **Disable ACLs** to disable them. To manage ACLs, you need specific IAM permissions. See [Grant permission to create data sources with ACLs disabled](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/setting-up.html#DisableAclOnDataSource) for more details. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details.
1. Authentication for existing Zendesk customers: Enter a name for your secret, a client ID, client secret, username, and password.
1. Authentication for new customers since 30 July 2024:
1. Register the application with Zendesk and follow their procedure: [Using OAuth authentication with your application](https://support.zendesk.com/hc/en-us/articles/4408845965210-Using-OAuth-authentication-with-your-application)
1. Set Client kind to Confidential.
1. For Redirect URL Enter the URL that Zendesk should use to grant access to the application. The URLs must be absolute and not relative. You can use localhost: `http://localhost` or `http://127.0.0.1`.
1. Implement an OAuth authorization flow:
1. Zendesk supports the authorization code grant flow to get access tokens. (Other grant flows have been deprecated.)
1. The flow doesn't use refresh tokens. The access token doesn't expire.
1. To get an authorization code, register users on the Zendesk authorization page: `https://{subdomain}.zendesk.com/oauth/authorizations/new`. Use the following parameters:
1. `response_type` - Zendesk returns an authorization code in the response, so specify code as the response type. For example: response\$1type=code.
1. `redirect_url` - The URL, which can be local, that Zendesk should use to send the user's decision to grant access to your application. For example: `http://localhost` or `http://127.0.0.1`.
1. `client_id` - The unique identifier obtained after registering the application with Zendesk.
1. `scope` - A space-separated list of scopes that control access to the Zendesk resources.
1. After this, Zendesk will ask for user approval. Once approved it will respond with an authorization code.
1. Obtain an access token from Zendesk. Include the following parameters in the request:
1. `grant_type` - Specify `authorization_code` as the value.
1. `code` - Use the authorization code received from Zendesk after the user has been granted access.
1. `client_id` - Use the unique identifier specified in an OAuth client in the Support admin interface Admin > Channels > API > OAuth Clients.
1. `client_secret` - Use the secret specified in an OAuth client in the Support admin interface Admin > Channels > API > OAuth Clients).
1. `redirect_uri` - The URL, which can be local, that Zendesk should use to send the user's decision to grant access to your application. For example: `http://localhost` or `http://127.0.0.1`.
1. `scope` – A space-separated list of scopes that control access to the Zendesk resources.
For example:
```
curl https://{subdomain}.zendesk.com/oauth/tokens \
-H "Content-Type: application/json" \
-d '{"grant_type": "authorization_code", "code": "{your_code}",
"client_id": "{your_client_id}", "client_secret": "{your_client_secret}",
"redirect_uri": "{your_redirect_url}", "scope": "read" }' \
-X POST
```
1. Use the access token in API calls.
1. **Configure VPC and security group – *optional*** – Choose whether you want to use a VPC. If you do, enter the following information:
1. **Subnets** – Select up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
1. **VPC security groups** – Choose up to 10 security groups that allow access to your data source. Ensure that the security group allows incoming traffic from Amazon EC2 instances and devices outside your VPC. For databases, security group instances are required.
For more information, see [VPC](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-vpc).
1. **IAM role** – Choose an existing IAM role or create an IAM role to access your repository credentials and index content.
**Note**
Creating a new service IAM role is recommended.
For more information, see [IAM role](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/zendesk-connector.html#zendesk-iam).
1. **Sync scope** – Set the content that you want to sync.
1. For **Maximum file size** – Specify the file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB.
1. **Additional configuration – optional** – Configure the following settings:
+ **Change log** – Select to update your index instead of syncing all your files.
+ **Organization name** – Enter the Zendesk organization names to filter your sync.
+ **Sync start date** – The date from which you want to index your content.
+ **Regex patterns** – Regular expression patterns to include or exclude certain files. You can add up to 100 patterns.
1. **Advanced settings**
**Document deletion safeguard** - *optional*–To safeguard your documents from deletion during a sync job, select **On** and enter an integer between 0 - 100. If the percentage of documents to be deleted in your sync job exceeds the percentage you selected, the delete phase will be skipped and no documents from this data source will be deleted from your index. For more information, see [Document deletion safeguard](connector-concepts.md#document-deletion-safeguard).
1. In **Sync run schedule**, for **Frequency** – Choose how often Amazon Q will sync with your data source. For more details, see [Sync run schedule](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-sync-run). To learn how to start a data sync job, see [Starting data source connector sync jobs](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/supported-datasource-actions.html#start-datasource-sync-jobs).
1. **Tags - *optional*** – Add tags to search and filter your resources or track your AWS costs. See [Tags](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/tagging.html) for more details.
1. **Field mappings** – A list of data source document attributes to map to your index fields.
**Note**
Add or update the fields from the **Data source details** page after you finish adding your data source. You can choose from two types of fields:
1. **Default** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can't edit these.
1. **Custom** – Automatically created by Amazon Q on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.
**Note**
Support for adding custom fields varies by connector. You won't see the **Add field** option if your connector doesn't support adding custom fields.
For more information, see [Field mappings](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-field-mappings).
1. In **Data source details**, choose **Sync now** to allow Amazon Q to begin syncing (crawling and ingesting) data from your data source. When the sync job finishes, your data source is ready to use.
**Note**
View CloudWatch logs for your data source sync job by selecting **View CloudWatch logs**. If you encounter a `Resource not found exception` error, wait and try again as logs may not be available immediately.
You can also view a detailed document-level report by selecting **View Report**. This report shows the status of each document during the crawl, sync, and index stages, including any errors. If the report is empty for an in-progress job, check back later as data is emitted to the report as events occur during the sync process.
For more information, see [Troubleshooting data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/troubleshooting-data-sources.html#troubleshooting-data-sources-not-indexed).
# Connecting Amazon Q Business to Zendesk using APIs
Using the API
You use the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) action to connect a data source to your Amazon Q application. You can also use the [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) action to modify an existing data source configuration.
Then, you use the `configuration` parameter to provide a JSON blob that conforms the AWS-defined JSON schema.
For an example of the API request, see [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) and [UpdateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateDataSource.html) in the Amazon Q API Reference.
## JSON schema
The following is the Zendesk JSON schema:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"connectionConfiguration": {
"type": "object",
"properties": {
"repositoryEndpointMetadata": {
"type": "object",
"properties": {
"hostUrl": {
"type": "string",
"pattern": "https:.*"
}
},
"required": [
"hostUrl"
]
}
},
"required": [
"repositoryEndpointMetadata"
]
},
"repositoryConfigurations": {
"type": "object",
"properties": {
"ticket": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "LONG", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "dd-MM-yyyy HH:mm:ss"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
},
"ticketComment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "LONG", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "dd-MM-yyyy HH:mm:ss"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
},
"ticketCommentAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "LONG", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "dd-MM-yyyy HH:mm:ss"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
},
"article": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "LONG", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "dd-MM-yyyy HH:mm:ss"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
},
"communityPostComment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "LONG", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "dd-MM-yyyy HH:mm:ss"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
},
"articleComment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "LONG", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "dd-MM-yyyy HH:mm:ss"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
},
"articleAttachment": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "LONG", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "dd-MM-yyyy HH:mm:ss"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
},
"communityTopic": {
"type": "object",
"properties": {
"fieldMappings": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"indexFieldName": {
"type": "string"
},
"indexFieldType": {
"type": "string",
"enum": ["STRING", "STRING_LIST", "LONG", "DATE"]
},
"dataSourceFieldName": {
"type": "string"
},
"dateFieldFormat": {
"type": "string",
"pattern": "dd-MM-yyyy HH:mm:ss"
}
},
"required": [
"indexFieldName",
"indexFieldType",
"dataSourceFieldName"
]
}
]
}
}
},
"required": [
"fieldMappings"
]
}
}
},
"secretArn": {
"type": "string",
"minLength": 20,
"maxLength": 2048
},
"additionalProperties": {
"type": "object",
"properties": {
"isCrawlAcl": {
"type": "boolean"
},
"maxFileSizeInMegaBytes": {
"type": "string"
},
"fieldForUserId": {
"type": "string"
},
"organizationNameFilter": {
"type": "array"
},
"sinceDate": {
"type": "string",
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$"
},
"inclusionPatterns": {
"type": "array"
},
"exclusionPatterns": {
"type": "array"
},
"isCrawTicket": {
"type": "string"
},
"isCrawTicketComment": {
"type": "string"
},
"isCrawTicketCommentAttachment": {
"type": "string"
},
"isCrawlArticle": {
"type": "string"
},
"isCrawlArticleAttachment": {
"type": "string"
},
"isCrawlArticleComment": {
"type": "string"
},
"isCrawlCommunityTopic": {
"type": "string"
},
"isCrawlCommunityPost": {
"type": "string"
},
"isCrawlCommunityPostComment": {
"type": "string"
}
}
},
"type": {
"type": "string",
"pattern": "ZENDESK"
},
"syncMode": {
"type": "string",
"enum": [
"FULL_CRAWL",
"FORCED_FULL_CRAWL",
"CHANGE_LOG"
]
},
"enableIdentityCrawler": {
"type": "boolean"
}
},
"version": {
"type": "string",
"anyOf": [
{
"pattern": "1.0.0"
}
]
},
"additionalProperties": false,
"required": [
"connectionConfiguration",
"repositoryConfigurations",
"additionalProperties",
"syncMode",
"secretArn",
"type"
]
}
```
The following table provides information about important JSON keys to configure.
| Configuration | Description |
| --- | --- |
| connectionConfiguration | Configuration information for the endpoint of the data source. |
| repositoryEndpointMetadata | The endpoint information for the data source. |
| hostURL | The Zendesk host URL. For example, https://yoursubdomain.zendesk.com. |
| repositoryConfigurations | Configuration information for the content of the data source. For example, configuring specific types of content and field mappings. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/zendesk-api.html) | A list of Zendesk objects and their metadata attributes that Amazon Q crawls and maps to Amazon Q index field names. The Zendesk data source field names must exist in your Zendesk custom metadata. |
| secretARN | The Amazon Resource Name (ARN) of an AWS Secrets Manager secret that contains the key-value pairs required to connect to your Zendesk. The secret must contain a JSON structure with the following keys: host URL, client ID, client secret, username, and password. |
| additionalProperties | Additional configuration options for your content in your data source. |
| isCrawlAcl | true to crawl Access Control Lists. Amazon Q Business crawls ACL information by default to ensure responses are generated only from documents your end users have access to. See [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization) for more details. |
| maxFileSizeInMegaBytes | Specify the maximum single file size limit in MBs that Amazon Q will crawl. Amazon Q will crawl only the files within the size limit you define. The default file size is 50MB. The maximum file size should be greater than 0MB and less than or equal to 50MB. |
| fieldForUserId | Specify field to use for UserId for ACL crawling. |
| organizationFilter | If you want, you can choose to index tickets that exist within a specific Organization |
| sinceDate | If you want, you can configure a sinceDate parameter so that the Zendesk connector will crawl based on the sinceDate. |
| inclusionPatterns | A list of regular expression patterns to include specific files in your Zendesk data source. Files that match the patterns are included in the index. Files that don't match the patterns are excluded from the index. If a file matches both an inclusion and exclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. |
| exclusionPatterns | A list of regular expression patterns to exclude specific files in your Zendesk data source. Files that match the patterns are excluded from the index. Files that don't match the patterns are included in the index. If a file matches both an exclusion and inclusion pattern, the exclusion pattern takes precedence, and the file isn't included in the index. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/zendesk-api.html) | Input true to index these types of content. |
| type | Specify ZENDESK as your data source type. |
| syncMode | Specify whether Amazon Q should update your index by syncing all documents or only new, modified, and deleted documents. You can choose between the following options: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/zendesk-api.html) |
| enableIdentityCrawler | Specify true to activate identity crawler. Identity crawler is activated by default. Crawling identity information on users and groups with access to certain documents is useful for user context filtering. Search results are filtered based on the user or their group access to documents. Amazon Q Business crawls identity information from your data source by default to ensure responses are generated only from documents end users have access to. For more information, see [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler). |
| version | The version of the template that's currently supported. |
# How Amazon Q Business connector crawls Zendesk ACLs
ACL crawling
Connectors support crawling ACL and identity information where applicable based on the data source. If you index documents without ACLs, all documents are considered public. Indexing documents with ACLs ensures data security.
Amazon Q Business supports crawling ACLs for document security by default.
When you connect an Zendesk data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your Zendesk instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end users' document access level.
The Zendesk connector supports enabling or disabling data ingestion for various entities including Tickets, Ticket Comments, Ticket Comment Attachments, Articles, Article Attachments, Article Comments, Community Topics, Community Posts, and Community Post Comments. For Ticket Comment Attachments and Article Attachments, the Zendesk connector allows applying include/exclude patterns based on file types, enabling more granular control over which attachments are ingested into Amazon Q Business.
**Roles/Permissions**: Zendesk roles define user permissions within the platform, including Admins, Agents, Light Agents, End Users, and Guide Admins. Admins have full control over settings, user management, and content access. Agents handle tickets, respond to customer queries, and may have restricted access based on group assignments. Light Agents can view and comment on tickets internally but cannot interact with customers. End Users are customers who can submit and track tickets. Guide Admins manage knowledge base content, including articles and community posts. Access control is determined by roles, groups, organizations, and user segments, ensuring the right level of visibility and permissions across the system. The Zendesk connector translates these roles into Amazon Q Business compatible ACLs, supporting View (Read), Edit, and Delete permissions.
**Identity Crawling**: The connector ensures accurate synchronization of user access control by retrieving and updating user identities, groups, and permissions. During this process, it fetches users from Zendesk Organizations, Groups, and User Segments, aligning them with the correct Access Control Lists (ACLs) in Amazon Q Business. This allows for consistent enforcement of role-based access, ensuring that users can only view content they are permitted to access. Additionally, identity crawling updates group memberships dynamically, reflecting changes in user roles, suspended accounts, and newly assigned permissions during scheduled syncs.
**Permissions Inheritance**: In Zendesk, permission inheritance varies across data source entities such as tickets, articles, and community content. For tickets, permissions are inherited based on roles (Requester, Assignee, Follower) and group or organization membership. Permissions for comments, notes and attachments of tickets are inherited from parent. Community topics and posts inherit permissions from assigned user segments, but Admins and Guide Admins have universal access.
**Change Management**: Change Log Mode in Amazon Q Business enables incremental updates by capturing modifications made to content in Zendesk. Instead of re-indexing all documents, it indexes only newly added, updated, or deleted items since the last crawl. Any changes to user or group access permissions are also recorded, ensuring accurate and up-to-date indexing. However, change log sync does not update ACLs for suspended or reactivated users.
**Failure Handling**: The connector follows a fail-close approach, meaning if there are permission-related issues or API failures, affected documents are skipped from ingestion rather than being made publicly accessible. This prevents unauthorized access while maintaining data integrity.
For more information, see:
+ [Authorization](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-authorization)
+ [Identity crawler](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-concepts.html#connector-identity-crawler)
+ [Understanding User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html)
# Zendesk data source connector field mappings
Field mappings
To improve retrieved results and customize the end user chat experience, Amazon Q Business enables you to map document attributes from your data sources to fields in your Amazon Q index.
Amazon Q offers two kinds of attributes to map to index fields:
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data source to Amazon Q index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q index fields.
When you connect Amazon Q to a data source, Amazon Q automatically maps specific data source document attributes to fields within an Amazon Q index. If a document attribute in your data source doesn't have a attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q index field. You create field mappings by editing your data source after your application and retriever are created.
To learn more about document attributes and how they work in Amazon Q, see [Document attributes and types in Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).
**Important**
Filtering using document attributes in chat is only supported through the API.
The Amazon Q Zendesk connector supports the following entities and the associated reserved and custom attributes.
**Topics**
+ [
## Tickets
](#zendesk-field-mappings-tickets)
+ [
## Ticket comments
](#zendesk-field-mappings-ticket-comments)
+ [
## Ticket comment attachment
](#zendesk-field-mappings-ticket-comment-attachment)
+ [
## Article
](#zendesk-field-mappings-article)
+ [
## Article comment
](#zendesk-field-mappings-article-comment)
+ [
## Article comment attachment
](#zendesk-field-mappings-article-comment-attachment)
+ [
## Community topic
](#zendesk-field-mappings-community-topic)
+ [
## Community post
](#zendesk-field-mappings-community-post)
+ [
## Community post comment
](#zendesk-field-mappings-community-post-comment)
## Tickets
Amazon Q supports crawling [Zendesk Tickets](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/) and offers the following ticket field mappings.
| Zendesk field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| ticketChannel | zd-channel | Custom | String |
| category | \$1category | Default | String |
| authors | \$1authors | Default | String list |
| assignee | zd\$1assignee | Custom | String |
| tags | zd\$1tags | Custom | String list |
| status | zd\$1status | Custom | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| organizationName | zd\$1organization\$1name | Custom | String |
## Ticket comments
Amazon Q supports crawling [Zendesk Ticket Comments](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_comments/) and offers the following ticket comment field mappings.
| Zendesk field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| authors | \$1authors | Default | String list |
| status | zd\$1status | Custom | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| organizationName | zd\$1organization\$1name | Custom | String |
## Ticket comment attachment
Amazon Q supports crawling [Zendesk Ticket Comment Attachments](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-attachments/) and offers the following ticket comment attachment field mappings.
| Zendesk field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| category | \$1category | Default | String |
| authors | \$1authors | Default | String list |
| status | zd\$1status | Custom | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| organizationName | zd\$1organization\$1name | Custom | String |
## Article
Amazon Q supports crawling [Zendesk Articles](https://developer.zendesk.com/api-reference/help_center/help-center-api/articles/) and offers the following article field mappings.
| Zendesk field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| authors | \$1authors | Default | String list |
| labels | zd\$1article\$1labels | Custom | String list |
| section | zd\$1article\$1section | Custom | String list |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
## Article comment
Amazon Q supports crawling [Zendesk Article Comments](https://developer.zendesk.com/api-reference/help_center/help-center-api/article_comments/) and offers the following article comment field mappings.
| Zendesk field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| authors | \$1authors | Default | String list |
| labels | zd\$1article\$1labels | Custom | String list |
| section | zd\$1article\$1section | Custom | String list |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
## Article comment attachment
Amazon Q supports crawling [Zendesk Article Comment Attachments](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-attachments/) and offers the following article comment attachment field mappings.
| Zendesk field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| authors | \$1authors | Default | String list |
| labels | zd\$1article\$1labels | Custom | String list |
| fileName | zd\$1file\$1name | Custom | String |
| fileType | \$1file\$1type | Default | String |
| fileSize | zd\$1file\$1size | Custom | Long (numeric) |
| section | zd\$1article\$1section | Custom | String list |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
## Community topic
Amazon Q supports crawling [Zendesk Community Topics](https://developer.zendesk.com/api-reference/help_center/help-center-templates/community_topic_page/) and offers the following community topic field mappings.
| Zendesk field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| topicName | zd\$1topic\$1name | Custom | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| category | \$1category | Default | String |
## Community post
Amazon Q supports crawling [Zendesk Community Posts](https://developer.zendesk.com/api-reference/help_center/help-center-templates/community_post_page/) and offers the following community post field mappings.
| Zendesk field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| postName | zd\$1post\$1name | Custom | String |
| topicName | zd\$1topic\$1name | Custom | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| category | \$1category | Default | String |
## Community post comment
Amazon Q supports crawling [Zendesk Community Post Comments](https://developer.zendesk.com/api-reference/help_center/help-center-api/post_comments/) and offers the following community post comment field mappings.
| Zendesk field name | Index field name | Description | Data type |
| --- | --- | --- | --- |
| postName | zd\$1post\$1name | Custom | String |
| topicName | zd\$1topic\$1name | Custom | String |
| sourceUrl | \$1source\$1uri | Default | String |
| createdAt | \$1created\$1at | Default | Date |
| updatedAt | \$1last\$1updated\$1at | Default | Date |
| category | \$1category | Default | String |
# IAM role for the Zendesk connector
IAM role
If you use the AWS CLI or an AWS SDK, you must create an AWS Identity and Access Management (IAM) policy before you create an Amazon Q resource. When you call the [CreateDataSource](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) operation, you provide the Amazon Resource Name (ARN) role with the policy attached.
If you use the AWS Management Console, you can create a new IAM role in the Amazon Q console or use an existing IAM role.
To learn more about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.
To connect your data source connector to Amazon Q, you must give Amazon Q an IAM role that has the following permissions:
+ Permission to access the `BatchPutDocument` and `BatchDeleteDocument` operations to ingest documents.
+ Permission to access the [User Store](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/connector-principal-store.html) API operations to ingest user and group access control information from documents.
+ Permission to access your AWS Secrets Manager secret to authenticate your data source connector instance.
+ **(Optional)** If you're using Amazon VPC, permission to access your Amazon VPC.
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQToGetSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:{{region}}:{{account_id}}:secret:[[secret_id]]"
]
},
{
"Sid": "AllowsAmazonQToDecryptSecret",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
],
"Condition": {
"StringLike": {
"kms:ViaService": [
"secretsmanager.*.amazonaws.com"
]
}
}
},
{
"Sid": "AllowsAmazonQToIngestDocuments",
"Effect": "Allow",
"Action": [
"qbusiness:BatchPutDocument",
"qbusiness:BatchDeleteDocument"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/index/{{index_id}}"
]
},
{
"Sid": "AllowsAmazonQToIngestPrincipalMapping",
"Effect": "Allow",
"Action": [
"qbusiness:PutGroup",
"qbusiness:CreateUser",
"qbusiness:DeleteGroup",
"qbusiness:UpdateUser",
"qbusiness:ListGroups"
],
"Resource": [
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}",
"arn:aws:qbusiness:{{region}}:{{account_id}}:application/{{application_id}}/index/{{index_id}}/data-source/*"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNI",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": [
"arn:aws:ec2:{{region}}:{{account_id}}:subnet/[[subnet_ids]]",
"arn:aws:ec2:{{region}}:{{account_id}}:security-group/[[security_group]]"
]
},
{
"Sid": "AllowsAmazonQToCreateAndDeleteNIForSpecificTag",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:RequestTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"AMAZON_Q"
]
}
}
},
{
"Sid": "AllowsAmazonQToCreateTags",
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateNetworkInterface"
}
}
},
{
"Sid": "AllowsAmazonQToCreateNetworkInterfacePermission",
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterfacePermission"
],
"Resource": "arn:aws:ec2:{{region}}:{{account_id}}:network-interface/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AMAZON_Q": "qbusiness_{{account_id}}_{{application_id}}_*"
}
}
},
{
"Sid": "AllowsAmazonQToDescribeResourcesForVPC",
"Effect": "Allow",
"Action": [
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DescribeVpcs",
"ec2:DescribeRegions",
"ec2:DescribeNetworkInterfacePermissions",
"ec2:DescribeSubnets"
],
"Resource": "*"
}
]
}
```
**To allow Amazon Q to assume a role, you must also use the following trust policy:**
```
{
"Version": "2012-10-17", ,
"Statement": [
{
"Sid": "AllowsAmazonQServicePrincipal",
"Effect": "Allow",
"Principal": {
"Service": "qbusiness.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "{{source_account}}"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
}
}
}
]
}
```
For more information on Amazon Q data source connector IAM roles, see [IAM roles for Amazon Q data source connectors](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/iam-roles.html#iam-roles-ds).
# Understand error codes in the Zendesk connector
Error Codes
The following table provides information about error codes you may see for the Zendesk connector and suggested resolutions.
| Error code | Error message | Suggested resolution |
| --- | --- | --- |
| ZND-5001 | Error validating credentials due to invalid username or password. | Provide a valid username/password. |
| ZND-5002 | Error validating credentials due to invalid client Id or client Secret. | Provide a valid Zendesk client Id or client Secret. |
| ZND-5100 | The host URL is null or empty. | Provide a valid host Url. |
| ZND-5101 | The username is null or empty. | Provide a valid username. |
| ZND-5102 | The password is null or empty. | Provide a valid password. |
| ZND-5103 | The Zendesk client Id is null or empty. | Provide a valid client Id. |
| ZND-5104 | The Zendesk client Secret is null or empty. | Provide a valid client Secret. |
| ZND-5105 | Invalid date format for field 'sinceDate'. | Date format should be yyyy-MM-dd HH:mm:ss. |
| ZND-5106 | Invalid value for field 'sinceDate'. | Since date should not be greater than the current date. |
| ZND-5107 | The datatype for the index field is invalid. | Only String, Date and Long formats are supported for field mappings. |
| ZND-5108 | The isCrawTicket value is invalid. | isCrawTicket should be a boolean value true or false. |
| ZND-5109 | The isCrawTicketComment value is invalid. | isCrawTicketComment should be a boolean value true or false. |
| ZND-5110 | The isCrawTicketCommentAttachment value is invalid. | isCrawTicketCommentAttachment should be a boolean value true or false. |
| ZND-5111 | The isCrawlArticle value is invalid. | isCrawlArticle should be a boolean value true or false. |
| ZND-5112 | The isCrawlArticleComment value is invalid. | isCrawlArticleComment should be a boolean value true or false. |
| ZND-5113 | The isCrawlArticleAttachment value is invalid. | isCrawlArticleAttachment should be a boolean value true or false. |
| ZND-5114 | The isCrawlCommunityTopic value is invalid. | isCrawlCommunityTopic should be a boolean value true or false. |
| ZND-5115 | The isCrawlCommunityPost value is invalid. | isCrawlCommunityPost should be a boolean value true or false. |
| ZND-5116 | The isCrawlCommunityPostComment value is invalid. | isCrawlCommunityPostComment should be a boolean value true or false. |
| ZND-5117 | Repository Configurations is null or empty. | Repository Configurations should not be null or empty value. |
| ZND-5118 | The Host Url pattern is not valid. | Provide a valid host url. Ex: 'https://\$1sub-domain\$1.zendesk.com/' or 'https://\$1sub-domain\$1.zendesk.com' |
| ZND-5119 | The URI is invalid. | Provide a valid URI. |
| ZND-5120 | The personal access token is null or empty. | Provide a valid patToken. |
| ZND-5121 | The auth type is incorrect. | The auth type should be OAuth2 or Oauth2-ImplicitGrantFlow. |
| ZND-5122 | The accessToken provided is expired, revoked, malformed or invalid. | Provide valid accessToken. |
| ZND-5123 | The access token doesn't have sufficient permission. | Check the user has sufficient permission to crawl. |
| ZND-5500 | Unable to fetch data from Zendesk. | Check your Zendesk account plan/subscription: it may have expired. |
| ZND-5501 | Unable to generate access token. | Check your Zendesk configuration and try again. |
| ZND-5502 | There was an error parsing the field value. The size has exceeded the maximum allowable limit. | The maximum size permitted is 1000 characters for the fields. |
| ZND-5503 | The url is invalid. | Provide valid URL. |