Connect Confluence Cloud

This page describes how to connect Confluence Cloud to Agentspace.

After you set up your data source and import data the first time, the data store syncs data from that source at a frequency that you select during setup.

Supported versions

The Confluence Cloud connector supports Confluence REST API versions v1 and v2.

Before you begin

Before you set up your connection:

1. Verify that you have administrator access to the Confluence instance and project.

2. (Optional) To retrieve user email addresses from Confluence Cloud, even when settings restrict email visibility, install the User Identity Accessor for Confluence Cloud app. You must be a Confluence Site administrator to install and configure this app. After you install the app, configure it to securely retrieve user email addresses. You might not need to install this app if the email addresses are publicly accessible.

3. Grant the Discovery Engine Editor role ( roles/discoveryengine.editor ). This role is required for the user to create the data store. To grant this role, do the following:

   1. In the Google Cloud console, go to the IAMpage.

      Go to IAM

   2. Locate the user account and click the Editicon edit .

   3. Grant the Discovery Engine Editor role to the user.

4. To enforce data source access control and secure data in Agentspace, ensure that you have configured your identity provider .

Set up authentication and permissions in Confluence

You can authenticate to Confluence by using OAuth client credentials or API token based authentication. The following sections provide information about how to create OAuth client credentials and API token.

Create OAuth client credentials

Use the following instructions to create a client ID and client secret, configure the required OAuth 2.0 scopes, set up permissions for users, retrieve your instance URL and ID, configure roles, and authenticate to sync data between Confluence Cloud and Agentspace. To enable OAuth 2.0 and obtain the client ID and secret, see OAuth 2.0 (3LO) apps in the Atlassian Developer documentation.

1. Create an OAuth 2.0 integration in the Atlassian Developer Console:

   1. Sign in to Atlassian Developer Console .

   2. Click the profile icon and select Developer console.

      

   3. Click Createand select OAuth 2.0 Integration.

      

   4. Enter a name for the app and do the following:

      1. Check the terms and conditions checkbox.

      2. Click Create.

         

      3. Click Authorization.

      4. In the Authorization typetable, click Addfor OAuth 2.0 (3LO).

         

   5. In the Callback URLfield, enter https://vertexaisearch.cloud.google.com/console/oauth/confluence_oauth.html

   6. Click Save changes.

      

If you see the warning: Your app doesn't have any APIs. Add APIs to your app, continue with the next procedure to configure OAuth 2.0. Otherwise, skip to step 4 in that procedure.

To configure OAuth 2.0 and retrieve the required credentials for your Confluence connector setup, do the following:

1. Enable OAuth 2.0:

   1. Click Permissions.

      

   2. Go to Confluence API.

   3. Click Add.

   4. Click Configure.

   5. Go to the Granular scopestab and click Edit scopes.

      

   6. Select the following scopes.

      • read:attachment:confluence
      • read:configuration:confluence
      • read:content.metadata:confluence
      • read:content-details:confluence
      • read:whiteboard:confluence
      • read:group:confluence
      • read:space:confluence
      • read:user:confluence

   7. Confirm that eight scopes are selected and save your changes.

2. Obtain the client ID and client secret:

   1. Click Distribution.

   2. Select Edit.

      

   3. Select Sharingto enable editing other fields.

   4. Fill out the remaining fields. Make sure to set Vendor nameto Googleand Privacy policyto https://policies.google.com .

   5. In the Personal data declarationsection, do the following:

      1. In the Does your app store personal data?list, select Yes.

      2. To confirm that you have implemented Personal Data Reporting API, select the I confirm that I've implemented the Personal Data Reporting APIcheckbox.

      3. Click Save changes.

   6. Select Settings, and then copy the values from the Client IDand Client secretfields.

      

3. Obtain the instance URL:

   1. Go to atlassian.net and sign in with your administrator account.
   2. Select the app you want to sync. For example, sync the first app.
   3. Find the instance URL. It appears as the subdomain in the address bar.

4. Obtain the instance ID:

   1. Open a new tab, copy the instance URL, and append /_edge/tenant_info to the instance URL. For example, https://<var>YOUR-INSTANCE</var>.atlassian.net/_edge/tenant_info .

   2. Navigate to the link to find the cloudId value. The cloudId is your instance ID.

      

Minimum OAuth scopes

The following table lists the minimum OAuth scopes required to create a Confluence Cloud connector:

Set up an API token in Confluence

If you plan to use an API token for authentication, you must create an API token without scopes. This connector doesn't support API token with scopes.

1. Sign in to Atlassian Console .
2. Click Create API token.
3. Enter a name for the API token.
4. Select an expiration date for the API token. The token expiration period ranges from 1 to 365 days.
5. Click Create.
6. Save the token for later use.

Obtain the instance URL

1. Go to atlassian.net and sign in with your administrator account.
2. Select the app you want to sync. For example, sync the first app.
3. Find the instance URL. It appears as the subdomain in the address bar.

Manage user visibility and grant roles

To set the user visibility, do the following:

1. Sign in to Atlassian Developer Console .

2. Click the user profile icon and go to Manage account.

   

3. Navigate to the Profile and visibility.

   

4. Go to Contactand set the Who can see thisas Anyone.

   

Grant a user an administrator role

Optionally, you can grant another user with an administrator role in Atlassian.

1. Sign in to Atlassian using an administrator account.

2. Click the menu icon and select your organization. Alternatively, you can go to admin.atlassian.com .

3. On the Appspage, click more_horiz (the ellipsis icon) next to Confluenceand select the Manage usersbutton.

   

4. Click Groupsunder User management.

5. On the Groupspage:

   1. Click Create group.
   2. Enter a name for the group.

   

   This group receives permissions required by the connector. Users added to this group inherit these permissions. The connector uses this group to authenticate and fetch documents.

6. On the group page, click Add product.

   1. Select User access adminas the product role.

   2. Click Add.

      

7. Click Add group membersto add the user account or group members that the connector uses to authenticate.

   

Install and configure User Identity Accessor for Confluence Cloud

If user email addresses aren't publicly accessible by default due to privacy settings in Confluence Cloud, you must install the User Identity Accessor for Confluence Cloudapp to securely retrieve user email addresses. If user email addresses are already publicly visible, you might not need to install the app. For more information about restricted email visibility, see Manage user visibility and grant roles .

Roles and permissions

To install and configure the User Identity Accessor for Confluence Cloudapp, you must have the appropriate administrative role and grant the required app-level permissions.

• Required role: You must be a Confluence Site administrator to install and configure the app.
• App-level permissions: You must grant the following permissions during the app installation:
  • Read Email Address : Allows the app to securely retrieve user email addresses, even when profile visibility is restricted.
  • App Storage scope : Enables the app to read and write to its storage device.

Install User Identity Accessor for Confluence Cloud

To install the User Identity Accessor for Confluence Cloudapp on your Confluence site, follow these steps:

1. Navigate to Atlassian Developer Console .

2. Review the Read Email Addressand App Storage scopepermissions and click Get app.

   

3. From the Select a site to install this app onlist, select the Confluence site where you want to install the app. This list displays only the sites for which you have administrator access.

   Note:You must be an administrator of at least one Confluence site to install the app.

4. Click Installto complete the app installation.

Configure User Identity Accessor for Confluence Cloud

After you've installed the User Identity Accessor for Confluence Cloudapp, configure an API key that your external system (for example, your Confluence Cloud Connector) uses to securely call the app's webtrigger to fetch emails.

Access the configuration page

To access the User Identity Accessor for Confluence Cloudapp's configuration page in Confluence Cloud, follow these steps:

1. In your Confluence Cloud instance, click the Settings⚙️ icon in the navigation menu.
2. Select Appsfrom the menu.
3. On the Apps administrationpage, locate your app, User Identity Accessor for Confluence Cloud, in the Manage appslist.

4. Click Configureor the link associated with your app. The app's dedicated configuration page opens within Confluence.

   

Set up the API key

To set up the API key on the configuration page, follow these steps:

1. In the API Key Configurationsection, specify the secret key for authenticating requests to the app's webtrigger. You can authenticate requests using either of the following methods:

   • Enter your own key: Type or paste your own strong, unique API key into the API Key field. Use a key of at least 20–30 characters with a mix of uppercase letters, lowercase letters, numbers, and symbols.

     

   • Generate a key: Click the Generate New Keybutton. The system generates and displays a strong, random key in the field.

     

     Important: Immediately copy the API key displayed in the field. For security reasons, you might be unable to view the full key again after saving or navigating away. If lost, you need to set or generate a new one.

2. Click Save API Key. A success message confirms that the key is securely saved.

Test the app configuration

Verify if the User Identity Accessor for Confluence Cloud app is configured correctly by sending a request from your external system and confirming that user email addresses are returned successfully.

Get the webtrigger URL

1. On the Apps administrationpage, locate the Webtrigger URLsection, which displays the unique URL specific to your Confluence site and this app installation:
   • Your external system must call this URL to request user emails.
   • The URL typically looks like: http://uuid/domain.net/x1/randomId . For example, https:// YOUR_INSTANCE_ID .hello.atlassian-dev.net/x1/ WEBTRIGGER_ID , where YOUR_INSTANCE_ID is your Confluence Cloud instance identifier and WEBTRIGGER_ID is the unique identifier for the webtrigger endpoint generated for your app.
2. Click the Copy URLbutton or copy the entire URL.

Configure your external system

• Configure your external system that needs to fetch Confluence user emails with the API key and webtrigger URL obtained in the previous steps.

  • Endpoint URL: The webtrigger URL you copied.
  • HTTP Method: POST

  • Required Headers:

    • Content-Type: application/json

    • X-Api-Key: YOUR_API_KEY

      Replace YOUR_API_KEY with the API key you set or generated in the Set up the API key section.

Example curl command

This example demonstrates calling the User Identity Accessor for Confluence Cloudwebtrigger, which accepts an array of account IDs and returns the email addresses.

 curl  
--location  
--request  
POST  
 'https:// YOUR_INSTANCE_ID 
.hello.atlassian-dev.net/x1/ ENDPOINT_PATH 
' 
  
 \ 
--header  
 'X-Api-Key: YOUR-API-KEY 
' 
  
 \ 
--header  
 'Content-Type: application/json' 
  
 \ 
--data-raw  
 '{ 
 "accountIds": [ 
 " ACCOUNT_ID_1 
", 
 " ACCOUNT_ID_2 
" 
 ] 
 }' 
 

Replace:

• YOUR_INSTANCE_ID with your Confluence Cloud instance ID
• ENDPOINT_PATH with the API endpoint path
• YOUR_API_KEY with the API key you set or generated in the Set up the API key section
• ACCOUNT_ID with Atlassian account IDs you want to target

Expected response

  [{ 
 "accountId" 
 : 
 " ACCOUNT_ID_1 
" 
 , 
 "emailAddress" 
 : 
 " EMAIL_ADDRESS_1 
" 
 }, 
  
 { 
 "accountId" 
 : 
 " ACCOUNT_ID_2 
" 
 , 
 "emailAddress" 
 : 
 " EMAIL_ADDRESS_2 
" 
 }] 
 

Replace:

• ACCOUNT_ID_X with actual Atlassian account IDs
• USER_EMAIL_X with user email addresses returned from your API call

Implement security best practices

To confirm the security of your API key, follow these recommendations:

• Store the API key securely within your Confluence Cloud Connector's configuration.
• Verify that all communication with the webhook URL occurs over HTTPS. This is the default for User Identity Accessor for Confluence Cloudwebtriggers.

Support for User Identity Accessor for Confluence Cloud

Support offerings are available from Google for the User Identity Accessor for Confluence Cloudapp that can include maintenance and regular updates to keep the app up-to-date. If you encounter any issues or have questions specific to the app functionality, contact Google Cloud Support .

Manage Confluence Cloud data stores

This section provides instructions on how to create, update, and upgrade a Confluence Cloud data store.

Create a Confluence Cloud data store

Update the data store

You can update the following data store parameters:

• Data store name
• Authentication credentials, such as client ID, client secret, user account, and API token.
• Max QPS and forge app parameters, such as the Confluence identity sync forge URL and client secret.
• Full sync frequency, incremental sync frequency, and real-time sync.
• Filter condition for ingesting entity data.

To update the data store, follow these steps:

1. In the Google Cloud console, go to the Agentspacepage.

   Agentspace

2. In the navigation menu, click Data stores.

3. Click the name of the data store that you want to update.

4. Update the following values:

   • To update the data store name, full sync frequency, or incremental sync frequency, click the Editicon edit .
   • To update the real-time sync frequency, click View/editnext to Real-time sync.
   • To update authentication credentials, click Re-authenticate, and then specify the values.
   • To update Max QPSor Forge app parameters, click View/edit Parameters, and then specify the values.
   • To update the filter condition for the entities, in the Entitiessection, click Edit parameters, and then click Filters.

Upgrade to a new data store

If you experience issues with the accuracy of the page entity search results, do the following to upgrade to the latest version of data store:

1. Identify whether you use the latest version of the data store:
   1. In the navigation menu, click Data Stores.
   2. Click the name of the data store.
   3. In the data store details page that appears, on the Entitiestab, click the Pageentity.
   4. On the Datapage, check whether the value of the Typefield. If the value is Unstructured data , the latest version of the data store is in use and no action is required. If the value is Structured data , proceed with the following steps to create and migrate to the new data store.
2. Create a new data store.
3. Make sure that one full sync gets completed for the new data store with the required data.
4. Add the new data store to the app.
5. Pause the syncs on the previous data store.
6. After you verify that the new data store is working as intended for the page entity search, delete the previous data store from the app.

Error messages

The following table describes the common error messages, their descriptions, and possible solutions when connecting Confluence Cloud with Agentspace.

Known limitations

• The legacy user management model is not supported for integration with Confluence Cloud. Only the centralized user management model is supported. For more information, see Atlassian organization consolidation guide
• The appearance of the macros that you added on Confluence pages might differ from user to user based on their access permissions.
• This connector doesn't support incremental sync for the spaces entity.
• You can't use a Google Cloud service account to authenticate to Confluence Cloud.

Next steps

• To attach your data store to an app, create an app and select your data store following the steps in Create an app .

• To preview how your search results appear after your app and data store are set up, see Preview search results .

• To enable alerts for the data store, see Configure alerts for third-party data stores .