# Connecting Jira to Amazon Q Business 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 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 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 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 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:///wiki/rest/api/user/current' --header 'Authorization: Basic ' ``` If your data source is connected as expected, the JSON response should resemble the following: ``` { "type": "known", "accountId": "accountId", "accountType": "atlassian", "email": "email", "publicName": "Administrator", "profilePicture": { "path": "/wiki/aa-avatar/", "width": 48, "height": 48, "isDefault": false }, "displayName": "Administrator", "isExternalCollaborator": false, "_expandable": { "operations": "", "personalSpace": "" }, "_links": { "self": "https:///wiki/rest/api/user?accountId=", "base": "https:///wiki", "context": "/wiki" } } ``` If your Jira connector is not connected correctly, you will see the following error: + CNF-5123: The profile value is invalid. Try again after sometime. To troubleshoot the issue, check your Jira URL and make sure it's correct. # Connecting Amazon Q Business to Jira using the console The following procedure outlines how to connect Amazon Q Business to Jira using the AWS Management Console. **Connecting Amazon Q to Jira** 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 **Jira** data source to your Amazon Q application. 1. Then, on the **Jira** 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 **Jira URL**. For example: *https://company.atlassian.net/*. 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. **Jira ID** – Your Jira email id, with domain. For example, *marymajor@gmail.com*. 1. **Password/Token** – Your Jira API token. For more information on creating a Jira token, see [API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens). 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/jira-connector.html#jira-iam). 1. In **Sync scope**, enter the following information: 1. Choose to either sync **All projects** or sync **Only specific projects**. If you choose to sync **Only specific projects**, enter the **Jira Project Key ID**. 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*** – Choose from the following options to limit the scope for content to be indexed. If no filters are specified, all content will be synced by default. + **Statuses** – Add status values to index. + **Additional elements** – Choose whether to index **Comments**, **Attachments**, or **Worklogs**. + **Issue types** – Optionally choose specific issue types to index. If no issue types are selected, all issue types will be indexed by default. + **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. **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 Jira using APIs 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 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 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 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 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 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 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 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 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 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 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 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 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 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. |