Snapshot Site

Index your Atlassian Confluence Cloud contents using the Amazon Q Confluence Cloud connector for Amazon Q Business

TutoSartup excerpt from this article:
One such enterprise data repository you can use to store content is Atlassian Confluence… Confluence is a team workspace that provides a place to create, and collaborate on various projects, products, or ideas… There are two Confluence offerings: Cloud – This is offered as a software as…

Amazon Q Business is a generative artificial intelligence (AI)-powered assistant designed to enhance enterprise operations. It’s a fully managed service that helps provide accurate answers to users’ questions while honoring the security and access restrictions of the content. It can be tailored to your specific business needs by connecting to your company’s information and enterprise systems using built-in connectors to a variety of enterprise data sources. Amazon Q Business enables users in various roles, such as marketing managers, project managers, and sales representatives, to have tailored conversations, solve business problems, generate content, take action, and more, through a web interface. This service aims to help make employees work smarter, move faster, and drive significant impact by providing immediate and relevant information to help them with their tasks.

One such enterprise data repository you can use to store content is Atlassian Confluence. Confluence is a team workspace that provides a place to create, and collaborate on various projects, products, or ideas. Team spaces help your teams structure, organize, and share work, so each user has visibility into the institutional knowledge of the enterprise and access to the information they need or answers to the questions they have.

There are two Confluence offerings:

  • Cloud – This is offered as a software as a service (SaaS) product. It’s always on and continuously updated.
  • Data Center (self-managed) – Here, you host Confluence on your infrastructure, which may be on premises or the cloud, allowing you to keep data within your chosen environment and manage it yourself.

Your users may need to get answers in Amazon Q Business from the content in Atlassian’s Confluence Cloud instance as a part of their work. For this you will need to configure an Amazon Q Confluence Cloud connector. As a part of this configuration, one of the steps is to configure the authentication of the connector so that it can authenticate with Confluence (Cloud) and then index the relevant content.

This post covers the steps to configure the Confluence Cloud connector for Amazon Q Business.

Types of documents

When you connect Amazon Q to a data source, what Amazon Q considers—and crawls—as a document varies by connector. The Confluence Cloud connector crawls the following as documents:

  • Spaces – Each space is considered a single document.
  • Pages – Each page is considered a single document.
  • Blogs – Each blog is considered a single document.
  • Comments – Each comment is considered a single document.
  • Attachments – Each attachment is considered a single document.

Metadata

Every document has structural attributes—or metadata—attached to it. Document attributes can include information such as document title, document author, time created, time updated, and document type.

When you connect Amazon Q Business to a data source, it automatically maps specific data source document attributes to fields within an Amazon Q Business index. If a document attribute in your data source doesn’t have an attribute mapping already available, or if you want to map additional document attributes to index fields, use the custom field mappings to specify how a data source attribute maps to an Amazon Q Business index field. You create field mappings by editing your data source after your application and retriever are created.

To learn more about the supported entities and the associated reserved and custom attributes for the Amazon Q Confluence connector, refer to Amazon Q Business Confluence (Cloud) data source connector field mappings.

Authentication types

An Amazon Q Business application requires you to use AWS IAM Identity Center to manage user access. Although it’s recommended to have an IAM Identity Center instance configured (with users federated and groups added) before you start, you can also choose to create and configure an IAM Identity Center instance for your Amazon Q Business application using the Amazon Q console.

You can also add users to your IAM Identity Center instance from the Amazon Q Business console, if you aren’t federating identity. When you add a new user, make sure that the user is enabled in your IAM Identity Center instance and they have verified their email ID. They need to complete these steps before they can log in to your Amazon Q Business web experience.

Your identity source in IAM Identity Center defines where your users and groups are managed. After you configure your identity source, you can look up users or groups to grant them single sign-on access to AWS accounts, applications, or both.

You can have only one identity source per organization in AWS Organizations. You can choose one of the following as your identity source:

  • IAM Identity Center directory – When you enable IAM Identity Center for the first time, it’s automatically configured with an IAM Identity Center directory as your default identity source. This is where you create your users and groups, and assign their level of access to your AWS accounts and applications.
  • Active Directory – Choose this option if you want to continue managing users in either your AWS Managed Microsoft AD directory using AWS Directory Service or your self-managed directory in Active Directory (AD).
  • External Identity Provider – Choose this option if you want to manage users in other external identity providers (IdPs) through the Security Assertion Markup Language (SAML) 2.0 standard, such as Okta.

Access control lists

Amazon Q Business connectors index access control list (ACL) information that’s attached to a Confluence document along with the document itself. For document ACLs, Amazon Q Business indexes the following:

  • User email address
  • Group name for the local group
  • Group name for the federated group

When you connect a Confluence (Cloud) data source to Amazon Q Business, the connector crawls ACL (user and group) information attached to a document from your Confluence (Cloud) instance. The information is used to determine which content can be used to construct chat responses for a given user, according the end-user’s document access permissions.

You configure user and group access to Confluence spaces using the space permissions page, in Confluence. Similarly for pages and blogs, you use the restrictions page. For more information about space permissions, see Space Permissions Overview on the Confluence Support website. For more information about page and blog restrictions, see Page Restrictions on the Confluence Support website.

An Amazon Q Business connector updates any changes in ACLs each time that your data source content is crawled. To capture ACL changes to make sure that the right end-users have access to the right content, re-sync your data source regularly.

Identity crawling for Amazon Q Business User Store

As stated earlier, Amazon Q Business crawls ACL information at the document level from supported data sources. In addition, Amazon Q Business crawls and stores principal information within each data source (local user alias, local group, and federated group identity configurations) into the Amazon Q Business User Store. This is useful when your application is connected to multiple data sources with different authorization and authentication systems, but you want to create a unified, access-controlled chat experience for your end-users.

Amazon Q Business internally maps the local user and group IDs attached to the document, to the federated identities of users and groups. Mapping identities streamlines user management and speeds up chat responses by reducing ACL information retrieval time during chat requests. Identity crawling, along with the authorization feature, helps filter and generate web experience content restricted by end-user context. For more information about this process, see Understanding Amazon Q Business User Store.

The group and user IDs are mapped as follows:

  • _group_ids – Group names are present on spaces, pages, and blogs where there are restrictions. They’re mapped from the name of the group in Confluence. Group names are always lowercase.
  • _user_id – Usernames are present on the space, page, or blog where there are restrictions. They’re mapped depending on the type of Confluence instance that you’re using. For Confluence Cloud, the _user_id is the account ID of the user.

Overview of solution

With Amazon Q Business, you can configure multiple data sources to provide a central place to search across your document repository. For our solution, we demonstrate how to index a Confluence repository using the Amazon Q Business connector for Confluence. In this blog we will:

  1. Configure an Amazon Q Business Application.
  2. Connect Confluence (Cloud) to Amazon Q Business.
  3. Index the data in the Confluence repository.
  4. Run a sample query to test the solution.

Prerequisites

Before you begin using Amazon Q Business for the first time, complete the following tasks:

  1. Set up your AWS account.
  2. Optionally, install the AWS Command Line Interface (AWS CLI).
  3. Optionally, set up the AWS SDKs.
  4. Consider AWS Regions and endpoints.
  5. Set up required permissions.
  6. Enable and configure an IAM Identity Center instance.

For more information, see Setting up for Amazon Q Business.

To set up the Amazon Q Business connector for Confluence, you need to complete additional prerequisites. For more information, see Prerequisites for connecting Amazon Q Business to Confluence (Cloud).

Create an Amazon Q Business application with the Confluence Cloud connector

As the first step towards creating a generative AI assistant, you configure an application. Then you select and create a retriever, and also connect any data sources. After this, you grant end-user access to users to interact with an application using the preferred identity provider, IAM Identity Center. Complete the following steps:

  1. On the Amazon Q Business console, choose Get started.
Figure 1: Initial Amazon Q for Business home page

Figure 1: Initial Amazon Q for Business home page

  1. On the Applications page, choose Create application.

Figure 2: Amazon Q for Business application creation page

  1. Enter a name for your application, select the level of service access, and connect to IAM Identity Center. (Note: The IAM Identity Center instance does not have to be in the same Region as Amazon Q Business.)
  2. Choose Create.

Figure 3: Amazon Q for Business application configuration page

For additional details on configuring the Amazon Q application and connecting to IAM Identity Center, refer to Creating an Amazon Q Business application environment.

  1. Select your retriever and index provisioning options.
  2. Choose Next.

Figure 4: Amazon Q for Business retriever selection page

For additional details on creating and selecting a retriever, refer to Creating and selecting a retriever for an Amazon Q Business application.

  1. Connect to Confluence as your data source.
  2. Enter a name and description.
  3. Select Confluence Cloud as the source and enter your Confluence URL.

Figure 5: Confluence connector page

  1. There are two options for Authentication: Basic authentication and OAuth 2.0 authentication. Select the best option depending on your use case.

Figure 6: Confluence connector authentication options

Before you connect Confluence (Cloud) to Amazon Q Business, you need to create and retrieve the Confluence (Cloud) credentials you will use to connect Confluence (Cloud) to Amazon Q Business. You also need to add any permissions needed by Confluence (Cloud) to connect to Amazon Q Business.

The following procedures give you an overview of how to configure Confluence (Cloud) to connect to Amazon Q Business using either basic authentication or OAuth 2.0 authentication.

Configure Confluence (Cloud) basic authentication for Amazon Q Business

Complete the following steps to configure basic authentication:

  1. Log in to your account from Confluence (Cloud). Note the username you logged in with. You will need this later to connect to Amazon Q Business.
  2. From your Confluence (Cloud) home page, note your Confluence (Cloud) URL from your Confluence browser URL. For example, https://example.atlassian.net. You will need this later to connect to Amazon Q Business.
  3. Navigate to the Security page in Confluence (Cloud).
  4. On the API tokens page, choose Create API token.

Figure 7: Confluence API token creation

  1. In the Create an API token dialog box, for Label, add a name for your API token.
  2. Choose Create.

Figure 8: Confluence API token labelling

  1. From the Your new API token dialog box, copy the API token and save it in your preferred text editor. You can’t retrieve the API token after you close the dialog box.

Figure 9: Copying your Confluence API token

  1. Choose Close.

You now have the username, Confluence (Cloud) URL, and Confluence (Cloud) API token you need to connect to Amazon Q Business with basic authentication.

For more information, see Manage API tokens for your Atlassian account in Atlassian Support.

Configure Confluence (Cloud) OAuth 2.0 authentication for Amazon Q Business

Complete the following steps to configure Confluence (Cloud) OAuth 2.0 authentication:

  1. Retrieve the username and Confluence (Cloud) URL.
  2. Configure an OAuth 2.0 app integration.
  3. Retrieve the Confluence (Cloud) client ID and client secret.
  4. Generate a Confluence (Cloud) access token.
  5. Generate a Confluence (Cloud) refresh token.
  6. Generate a new Confluence (Cloud) access token using a refresh token.

Retrieve the username and Confluence (Cloud) URL

Complete the following steps:

  1. Log in to your account from Confluence (Cloud). Note the username you logged in with. You will need this later to connect to Amazon Q Business.
  2. From your Confluence (Cloud) home page, note your Confluence (Cloud) URL from your Confluence browser URL. For example, https://example.atlassian.net. You will need this later to both configure your OAuth 2.0 token and connect to Amazon Q Business.

Configuring an OAuth 2.0 app integration

Complete the following steps:

  1. Log in to your account from the Atlassian Developer page.
  2. Choose the profile icon in the top-right corner and on the dropdown menu, choose Developer console.

    Figure 10: Logging into the Confluence Developer Console

  3. On the welcome page, choose Create and choose OAuth 2.0 integration.

    Figure 11: Creating your Confluence OAuth 2.0 token

  4. Under Create a new OAuth 2.0 (3LO) integration, for Name, enter a name for the OAuth 2.0 application you’re creating. Then, read the Developer Terms, and select I agree to be bound by Atlassian’s developer terms checkbox, if you do.
  5. Select Create.

    Figure 12: Creating your Confluence OAuth 2.0 integration

    The console will display a summary page outlining the details of the OAuth 2.0 app you created.

    Figure 13: Your Confluence application

  6. Still in the Confluence console, in the navigation pane, choose Authorization.
  7. Choose Add to add OAuth 2.0 (3LO) to your app.

    Figure 14: Adding OAuth 2.0 to your Confluence app

  8. Under OAuth 2.0 authorization code grants (3LO) for apps, for Callback URL, enter the Confluence (Cloud) URL you copied, then choose Save changes.

    Figure 15: Adding OAuth 2.0 to your Confluence app (part 2)

  9. Under Authorization URL generator, choose Add APIs to add APIs to your app. This will redirect you to the Permissions page.
  10. On the Permissions page, for Scopes, navigate to User Identity API. Select Add, then select Configure.

    Figure 16: Configuring Permissions for your Confluence app

  11. Under User Identity API, choose Edit Scopes, then add the following read scopes:
    1. read:me – View active user profile.
    2. read:account – View user profiles.

      Figure 17: Configuring Scopes for your Confluence app

  12. Choose Save and return to the Permissions page.
  13. On the Permissions page, for Scopes, navigate to Confluence API. Select Add, and then select Configure.

    Figure 18: Configuring Permissions for your Confluence app (part 2)

  14. Under Confluence API, make sure you’re on the Classic scopes tab.

    Figure 19: Configuring Permissions for your Confluence app (part 3)

  15. Choose Edit Scopes and add the following read scopes:
    1. read:confluence-space.summary – Read Confluence space summary.
    2. read:confluence-props – Read Confluence content properties.
    3. read:confluence-content.all – Read Confluence detailed content.
    4. read:confluence-content.summary – Read Confluence content summary.
    5. read:confluence-content.permission – Read content permission in Confluence.
    6. read:confluence-user – Read user.
    7. read:confluence-groups – Read user groups.
  16. Choose Save.
  17. Navigate to the Granular scopes

    Figure 20: Configuring Permissions for your Confluence app (part 4)

  18. Choose Edit Scopes and add the following read scopes:
    1. read:content:confluence – View detailed contents.
    2. read:content-details:confluence – View content details.
    3. read:space-details:confluence – View space details.
    4. read:audit-log:confluence – View audit records.
    5. read:page:confluence – View pages.
    6. read:attachment:confluence – View and download content attachments.
    7. read:blogpost:confluence – View blog posts.
    8. read:custom-content:confluence – View custom content.
    9. read:comment:confluence – View comments.
    10. read:template:confluence – View content templates.
    11. read:label:confluence – View labels.
    12. read:watcher:confluence – View content watchers.
    13. read:group:confluence – View groups.
    14. read:relation:confluence – View entity relationships.
    15. read:user:confluence – View user details.
    16. read:configuration:confluence – View Confluence settings.
    17. read:space:confluence – View space details.
    18. read:space.permission:confluence – View space permissions.
    19. read:space.property:confluence – View space properties.
    20. read:user.property:confluence – View user properties.
    21. read:space.setting:confluence – View space settings.
    22. read:analytics.content:confluence – View analytics for content.
    23. read:content.permission:confluence – Check content permissions.
    24. read:content.property:confluence – View content properties.
    25. read:content.restriction:confluence – View content restrictions.
    26. read:content.metadata:confluence – View content summaries.
    27. read:inlinetask:confluence – View tasks.
    28. read:task:confluence – View tasks.
    29. read:permission:confluence – View content restrictions and space permissions.
    30. read:whiteboard:confluence – View whiteboards.
    31. read:app-data:confluence – Read app data.

For more information, see Implementing OAuth 2.0 (3LO) and Determining the scopes required for an operation in Atlassian Developer.

Retrieve the Confluence (Cloud) client ID and client secret

Complete the following steps:

  1. In the navigation pane, choose Settings.
  2. In the Authentication details section, copy and save the following in your preferred text editor:
    1. Client ID – You enter this as the app key on the Amazon Q Business console.
    2. Secret – You enter this as the app secret on the Amazon Q Business console.

Figure 21: Retrieving Confluence app authentication details

You need these to generate your Confluence (Cloud) OAuth 2.0 token and also to connect Amazon Q Business to Confluence (Cloud).

For more information, see Implementing OAuth 2.0 (3LO) and Determining the scopes required for an operation in the Atlassian Developer documentation.

Generate a Confluence (Cloud) access token

Complete the following steps:

  1. Log in to your Confluence account from the Atlassian Developer page.
  2. Open the OAuth 2.0 app you want to generate a refresh token for.
  3. In the navigation pane, choose Authorization.
  4. For OAuth 2.0 (3LO), choose Configure.
  5. On the Authorization page, under Authorization URL generator, copy the URL for Granular Confluence API authorization URL and save it in your preferred text editor.

Figure 22: Retrieving Confluence API URL details

The URL is in 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_text.

For more information, see What is the state parameter used for? in the Atlassian Support documentation.

  1. Open your preferred web browser and enter the authorization URL you copied into the browser URL.
  2. On the page that opens, make sure everything is correct and choose Accept.

Figure 23: Testing a Confluence API URL

You will be returned to your Confluence (Cloud) home page.

  1. Copy the URL of the Confluence (Cloud) home page and save it in your preferred text editor.

The URL contains the authorization code for your application. You will need this code to generate your Confluence (Cloud) access token. The whole section after code= is the authorization code.

  1. Navigate to Postman.

If you don’t have Postman installed on your local system, you can also choose to use cURL to generate a Confluence (Cloud) access token. Use the following cURL command to do so:

curl --location 'https://auth.atlassian.com/oauth/token' 
--header 'Content-Type: application/json' 
--data '{"grant_type": "authorization_code",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"code": "AUTHORIZATION_CODE",
"redirect_uri": "YOUR_CALLBACK_URL"}'
  1. If, however, you have Postman installed, on the main Postman window, choose POST as the method, then enter the following URL: https://auth.atlassian.com/oauth/token.
  2. Choose Body, then choose raw and JSON.

Figure 24: Testing a Confluence access token in Postman

  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. Choose Send.

If everything is configured correctly, Postman will return an access token.

  1. Copy the access token and save it in your preferred text editor. You will need it to connect Confluence (Cloud) to Amazon Q Business.

For more information, see Implementing OAuth 2.0 (3LO) in the Atlassian Developer documentation.

Generate a Confluence (Cloud) refresh token

The access token you use to connect Confluence (Cloud) to Amazon Q Business using OAuth 2.0 authentication expires after 1 hour. When it expires, you can either repeat the whole authorization process and generate a new access token, or generate a refresh token.

Refresh tokens are implemented using a rotating refresh token mechanism. Each time they’re used, rotating refresh tokens issues a new limited-life refresh token that is valid for 90 days. Each new rotating refresh token resets the inactivity expiry time and allocates another 90 days. This mechanism improves on single persistent refresh tokens by reducing the period in which a refresh token can be compromised and used to obtain a valid access token. For additional details, see OAuth 2.0 (3LO) apps in the Atlassian Developer documentation.

To generate a refresh token, you add a %20offline_access parameter to the end of the scope value in the authorization URL you used to generate your access token. Complete the following steps to generate a refresh token:

  1. Log in to your account from the Atlassian Developer page.
  2. Open the OAuth 2.0 app you want to generate a refresh token for.
  3. In the navigation pane, choose Authorization.
  4. For OAuth 2.0 (3LO), choose Configure.
  5. On the Authorization page, under Authorization URL generator, copy the URL for Granular Confluence API authorization URL and save it in your preferred text editor.

Figure 25: Retrieving Confluence API URL details

  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_text.

For more information, see What is the state parameter used for? in the Atlassian Support documentation.

  1. 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 your preferred web browser and enter the modified authorization URL you copied into the browser URL.
  2. On the page that opens, make sure everything is correct and then choose Accept.

Figure 26: Testing a Confluence API URL

You will be returned to the Confluence (Cloud) console.

  1. Copy the URL of the Confluence (Cloud) home page and save it in a text editor of your choice.

The URL contains the authorization code for your application. You will need this code to generate your Confluence (Cloud) refresh token. The whole section after code= is the authorization code.

  1. Navigate to Postman.

If you don’t have Postman installed on your local system, you can also choose to use cURL to generate a Confluence (Cloud) access token. Use the following cURL command to do so:

curl --location 'https://auth.atlassian.com/oauth/token' 
--header 'Content-Type: application/json' 
--data '{"grant_type": "authorization_code",
"client_id": "YOUR CLIENT ID",
"client_secret": "YOUR CLIENT SECRET",
"code": "AUTHORIZATION CODE",
"redirect_uri": "YOUR CALLBACK URL"}'
  1. If, however, you have Postman installed, on the main Postman window, choose POST as the method, then enter the following URL: https://auth.atlassian.com/oauth/token.
  2. Choose Body on the menu, then choose raw and JSON.

Figure 27: Retrieving a Confluence refresh token in Postman

  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. Choose Send.

If everything is configured correctly, Postman will return a refresh token.

  1. Copy the refresh token and save it using your preferred text editor. You will need it to connect Confluence (Cloud) to Amazon Q Business.

For more information, see Implementing a Refresh Token Flow in the Atlassian Developer documentation.

Generate a new Confluence (Cloud) access token using a refresh token

You can use the refresh token you generated to create a new access token and refresh token pair when an existing access token expires. Complete the following steps to generate a refresh token:

  1. Copy the refresh token you generated following the steps in the previous section.
  2. Navigate to Postman.

If you don’t have Postman installed on your local system, you can also choose to use cURL to generate a Confluence (Cloud) access token. Use the following cURL command to do so:

curl --location 'https://auth.atlassian.com/oauth/token' 
--header 'Content-Type: application/json' 
--data '{"grant_type": "refresh_token",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"refresh_token": "YOUR_REFRESH_TOKEN"}'
  1. In the Postman main window, choose POST as the method, then enter the following URL: https://auth.atlassian.com/oauth/token.
  2. Choose Body from the menu and choose raw and JSON.

Figure 28: Using a Confluence refresh token in Postman

  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. Choose Send.

If everything is configured correctly, Postman will return a new access token and refresh token pair in the following format:

{"access_token": "string,
"expires_in": "expiry time of access_token in seconds",
"scope": "string",
"refresh_token": "string"}

For more information, see Implementing a Refresh Token Flow and How do I get a new access token, if my access token expires or is revoked? in the Atlassian Developer documentation.

Continue creating your application

Complete the following steps to continue creating your application:

  1. For AWS Secrets Manager secret, choose an existing secret or create an AWS Secrets Manager secret to store your Confluence authentication credentials. If you choose to create a secret, an AWS Secrets Manager window opens. Enter the following information in the window:
    1. For Secret name, enter a name for your secret.
    2. Enter the information you generated earlier:
      1. If using Basic Authentication, enter your Secret name, User name, and Password (Confluence API Token) that you generated and downloaded from your Confluence account.
      2. If using OAuth2.0 Authentication, enter the Secret name, App key, App secret, Access token, and Refresh token that you created in your Confluence account.
    3. Choose Save and add secret.For additional details on creating a Secrets Manager secret, refer to Create an AWS Secrets Manager secret.
  2. Choose the secret you created to use for your Confluence connector.

    Figure 29: Selecting a secret in Secrets Manager

  3. Under Configure VPC and security group, you can choose whether you want to use a VPC (Optional). If you do (which we recommend), enter the following information:
    1. For Subnets, enter up to 6 repository subnets that define the subnets and IP ranges the repository instance uses in the selected VPC.
    2. For VPC security groups, Choose up to 10 security groups that allow access to your data source.For more information, see Virtual private cloud.

      Figure 30: Configuring VPC and Security Group in Amazon Q Business

  4. Under Identity crawler, confirm that crawling is enabled.Amazon Q Business crawls identity information from your data source by default to make sure the responses from your connected data sources are generated only from documents end-users have access to. For more information, see Identity crawler.By default, an Amazon Q Business application is configured to respond to end user chat queries using only enterprise data. If you would like Amazon Q Business to use the underlying LLM knowledge to generate responses when it can’t find the information from your connected data sources, you can enable this in the Response settings under your application guardrails.
  5. Under IAM role, choose an existing AWS Identity and Access Management (IAM) role or create an IAM role to access your repository credentials and index content.Creating a new service role is recommended. For more information, see IAM role for Amazon Q Confluence (Cloud) connector.

    Figure 31: Configuring IAM role in Amazon Q Business

  6. Under Sync scope, choose from the following options:
    1. For Sync contents, you can choose to sync from the following entity types: pages, page comments, page attachments, blogs, blog comments, blog attachments, personal spaces, archived spaces, and archived pages.
    2. For Maximum single file size, specify the file size limit in megabytes that Amazon Q Business will crawl. Amazon Q Business will crawl only the files within the size limit you define. The file size should be greater than 0 MB and less than or equal to 50 MB.
  7. Under Additional configuration, for Space and regex patterns, specify whether to include or exclude specific spaces in your index with the following settings:
    1. Space key – For example, my-space-123.
    2. URL – For example, .*/MySite/MyDocuments/.
    3. File type – For example, .*.pdf, .*.txt.
    4. For Entity title regex patterns, specify regular expression patterns to include or exclude certain blogs, pages, comments, and attachments by titles.

      Figure 32: Configuring scopes and regexes in Amazon Q Business

  8. Under 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 Business for the first time, all content is synced by default. You have the following options:
    1. Full sync – Sync all content regardless of the previous sync status.
    2. New, modified, or deleted content sync – Sync only new, modified, and deleted documents.
  9. Under Sync run schedule, for Frequency, choose how often Amazon Q Business will sync with your data source. For more details, see Sync run schedule.
  10. Under Tags, you can optionally add tags to search and filter your resources or track your AWS costs. See Tagging resources for more details.

    Figure 33: Configuring sync mode, sync frequency, and tagging

  11. Under Field mappings, select the data source document attributes to map to your index fields. Add the fields from the Data source details page after you finish adding your data source. You can choose from two types of fields:
    1. Default – Automatically created by Amazon Q Business on your behalf based on common fields in your data source. You can’t edit these.
    2. Custom – Automatically created by Amazon Q Business on your behalf based on common fields in your data source. You can edit these. You can also create and add new custom fields.For more information, see Field mappings.
  12. To finish connecting your data source to Amazon Q, choose Add data source.

    Figure 34: Mapping Confluence fields in Amazon Q Business

  13. After the Confluence connector is created, you’re redirected to the Connect data sources page, where you can add additional data sources if needed.
  14. Choose Next to continue.
  15. Under Add or assign users and groups, you can to assign users or groups from IAM Identity Center. If you have the appropriate permissions, you have the ability to add new users. Select the appropriate option for you.
  16. Choose Next.

    Figure 35: Assigning users/ groups and Web experience service access in Amazon Q Business

  17. Under Assign users and groups, you can choose the users or groups you want to add to your Amazon Q Business application. (In order for a user to get an answer from Amazon Q Business, the user IDs added in IAM Identity Center need to match the user IDs in Confluence.)
  18. In Web experience service access, enter the following information:
    1. For Choose a method to authorize Amazon Q Business – A service access role assumed by end users when they sign in to your web experience that grants them permission to start and manage conversations in Amazon Q Business. You can choose to use an existing role or create a new role.
    2. Service role name – A name for the service role you created for easy identification on the console.
  19. Select Create application.
  20. Once the application is created, navigate to the Data source details section, choose Sync now to allow Amazon Q Business to begin syncing (crawling and ingesting) data from your data source.

When the sync job is complete, your data source is ready to use.

The time the sync will take depends on the size of your Confluence environment. Check back periodically to see if the sync has finished.

Run a sample query to test the solution

When the sync on your data source is complete, you can deploy the web experience to test the solution. For additional details for setting up the Amazon Q Business web experience, see Customizing an Amazon Q Business web experience.

Figure 37: Amazon Q Business web experience URLs

After you’re signed in to the web experience, try out a question based on information in your Confluence Cloud. The following screenshots show some examples.

Figure 38: Sample Amazon Q Business web experience prompt and completion

Figure 39: Sample Amazon Q Business web experience prompt and completion (part 2)

Figure 40: Sample Amazon Q Business web experience prompt and completion (part 3)

Amazon Q Business generates a response, as well as the citations to where the information came from. You can click the links in the citation to go directly to the source page.

Troubleshooting and FAQs

For information on troubleshooting your connector, see Troubleshooting your Amazon Q Business Confluence (Cloud) connector.

Refer to Amazon Q Business FAQs for frequently asked questions.

Clean up

If you no longer need your Amazon Q Business application, make sure to delete it to avoid unwanted costs. When you delete your application, it will remove the associated index and data connectors.

Figure 41: Deleting Amazon Q Business confluence connector

Conclusion

In this post, we provided an overview of Amazon Q Business Confluence Cloud connector and how you can use it for seamless integration of generative AI assistance to your Confluence Cloud. By using a single interface for the variety of data sources in the organization, you can enable employees to be more data-driven, efficient, prepared, and productive.

To learn more about Amazon Q Business connector for Confluence Cloud, refer to Connecting Confluence (Cloud) to Amazon Q Business.

About the Authors

Tyler Geary is a Solutions Architect at Amazon Web Services (AWS), where he is a member of the Enterprise Financial Services team, focusing on Insurance customers. He helps his customers identify business challenges and opportunities, tying them back to innovative solutions powered by AWS, with a particular focus on Generative AI. In his free time, Tyler enjoys hiking, camping, and spending time in the great outdoors.

Sumeet Tripathi is an Enterprise Support Lead (TAM) at AWS in North Carolina. He has over 17 years of experience in technology across various roles. He is passionate about helping customers to reduce operational challenges and friction. His focus area is AI/ML and Energy & Utilities Segment. Outside work, He enjoys traveling with family, watching cricket and movies.

Vishal Naik is a Sr. Solutions Architect at Amazon Web Services (AWS). He is a builder who enjoys helping customers accomplish their business needs and solve complex challenges with AWS solutions and best practices. His core area of focus includes Generative AI and Machine Learning. In his spare time, Vishal loves making short films on time travel and alternate universe themes.

Index your Atlassian Confluence Cloud contents using the Amazon Q Confluence Cloud connector for Amazon Q Business
Author: Tyler Geary