Connect Jira Cloud

This page describes how to connect Jira 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 Jira Cloud connector supports version 2 of the JIRA Cloud REST API.

Before you begin

Before you set up your connection, do the following:

• Verify that you have Jira organization administrator access to the Jira instance and project. With the administrator access, you can set up minimum permissions and provide access privileges to user groups. For information about how to verify Jira organization administrator access, see Verify Jira organization administrator access.

• (Optional) To retrieve user email addresses from Jira Cloud, even when settings restrict email visibility, install the User Identity Accessor for Jira Cloud app. You must be a Jira 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 email addresses are already publicly accessible.

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

• To enable OAuth 2.0 and obtain the client ID and secret, see OAuth 2.0 (3LO) apps in the Atlassian developer documentation.

Verify Jira organization administrator access

1. Login to Atlassian with your user credentials.

2. Select a Jira app.

   

3. Click Settings.

If you see the System option, then you have Jira organization administrator access. Otherwise, request your Jira organization administrator to provide access.

Create an OAuth 2.0 integration

1. Sign in to the Atlassian Developer Console.

2. Click the profile icon and select Developer console.

   

3. Click Create and select OAuth 2.0 Integration.

   

4. Enter a name for the app.

5. Select the checkbox to agree to Atlassian's developer terms.

6. Click Create.

   

7. Click Authorization.

8. In the Authorization type table, select Add for OAuth 2.0 (3LO).

   

9. In the Callback URL field, enter https://vertexaisearch.cloud.google.com/console/oauth/jira_oauth.html.

10. Click Save changes.

    

Configure the minimum permissions required for the application

1. On the application page, click Permissions.

   

2. Go to Jira API and click Add.

3. Click Configure.

4. Go to the Classic scopes tab.

5. Click Edit scopes and select the following permissions:

   • read:jira-user
   • read:jira-work

   

6. Confirm that the two scopes are selected, and then save your changes.

7. Go to the Granular scopes tab.

8. Click Edit scopes and select the following permissions:

   • read:issue-security-level:jira
   • read:issue-security-scheme:jira
   • read:group:jira
   • read:user:jira
   • read:avatar:jira
   • read:audit-log:jira

   

Minimum permissions

The following tables list the minimum permissions required to create a Jira Cloud connector.

Classic scopes

Granular scopes

Obtain a client ID and client secret

1. Click Distribution and select Edit.
2. Select Sharing to enable editing other fields.
3. Fill out the remaining fields:
   1. For Vendor, enter Google.
   2. For Privacy policy, enter https://policies.google.com.
   3. For Does your app store personal data?, select Yes.
   4. Select I confirm that I've implemented the personal data reporting API checkbox. For more information, see Personal data reporting API.

      

4. Click Save changes.

5. Click Settings to copy your Client ID and Client secret.

   

Obtain an instance ID and instance URL

1. 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://YOUR_INSTANCE.atlassian.net/_edge/tenant_info.

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

      

2. 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 (the subdomain in the address bar).

Manage user visibility and grant roles

To set the email visibility in the Atlassian account, do the following:

1. Sign in to the Atlassian Developer Console.

2. Click the profile icon and select Developer console.

3. Click the user profile icon and select Manage account.

   

4. Navigate to the Profile and visibility.

   

5. Go to Contact and set the Who can see this as Anyone.

   

To set the email visibility in the Jira administrator account, do the following:

1. Sign in to Atlassian with your user credentials.

2. Select a Jira app.

3. Click Settings > System.

4. Select General Configuration in the left pane.

5. Click Edit Settings.

6. For User email visibility, select Public.

   

7. Click Update.

To grant the Jira administrator the Discovery Engine Editor role in the Google Cloud console, do the following:

1. In the Google Cloud console, go to the Agentspace page.

2. Navigate to IAM.

   Go to IAM

3. Locate the user account which has administrator access in Jira and click the Edit icon edit.

4. Grant the Discovery Engine Editor role to the administrator.

To grant a user an administrator role in Atlassian, do the following:

1. Sign in to Atlassian using an organization administrator account.

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

3. On the Admin page, click the product and select the Manage users button.

   

4. Click Groups under User management.

5. On the Groups page:

   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.

1. On the group page, click Add product.

2. Select User access admin as the role for Jira.

3. Select Product admin as the role for Jira administration.

   

4. Click Grant Access.

5. Click Add group members to add a user account or group members that the connector uses to authenticate and access the required resources.

   

Install and configure User Identity Accessor for Jira Cloud

If user email addresses aren't publicly accessible by default due to privacy settings in Jira Cloud, you must install the User Identity Accessor for Jira Cloud app 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 Jira Cloud app, you must have the appropriate administrative role and grant the required app-level permissions.

• Required role: You must be a Jira 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 Jira Cloud

To install the User Identity Accessor for Jira Cloud app on your Jira Cloud site, follow these steps:

1. Navigate to Atlassian Developer Console.

2. Review the Read Email Address and App Storage scope permissions and click Get app.

   

3. From the Select a site to install this app on list, select the Jira 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 Jira site to install the app.

4. Click Install to complete the app installation.

Configure User Identity Accessor for Jira Cloud

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

Access the configuration page

To access the User Identity Accessor for Jira Cloud app's configuration page, follow these steps:

1. In your Jira Cloud instance, click the Settings ⚙️ icon in the navigation menu.
2. Select Apps from the menu.
3. On the Apps administration page, locate your app, User Identity Accessor for Jira Cloud, in the Manage apps list.

4. Click Configure or the link associated with your app. The app's dedicated configuration page opens within Jira Cloud.

   

Set up the API key

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

1. In the API Key Configuration section, 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 Key button. 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 Jira 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 administration page, locate the Webtrigger URL section, which displays the unique URL specific to your Jira 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 Jira Cloud instance identifier and WEBTRIGGER_ID is the unique identifier for the webtrigger endpoint generated for your app.
2. Click the Copy URL button or copy the entire URL.

Configure your external system

• Configure your external system that needs to fetch Jira 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 Jira Cloud webtrigger, 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 Jira 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 Jira Cloud Connector's configuration.
• Verify that all communication with the webhook URL occurs over HTTPS. This is the default for User Identity Accessor for Jira Cloud webtriggers.

Support for User Identity Accessor for Jira Cloud

Support offerings are available from Google for the User Identity Accessor for Jira Cloud app 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. For more information, see Getting Cloud Customer Care.

Create a Jira Cloud data store

Enable real-time sync

To enable real-time sync for a Jira Cloud data source connector, follow these steps:

Generate a webhook URL

1. Navigate to the Agentspace page, and in the navigation menu, click Data Stores.
2. Select a Jira Cloud data store.

3. Click View/Edit in the Realtime sync row.

   

4. In the View and edit realtime sync parameters dialog, do the following:

   1. To turn on real-time sync, click the Enable realtime sync toggle.
   2. Enter a value in the Client secret field and copy it. You need this value again when creating a webhook in the Jira administration console.
   3. Click Save.

      

5. After the status of Realtime sync changes to Running, click View/Edit.

   

6. In the View and edit realtime sync parameters dialog, do the following:

   1. Copy the Webhook URL.
   2. Click Close.

      

Create a webhook

1. Sign in to the Jira administration console.
2. Click Settings and select System.
3. In the System settings pane, select Webhooks.
4. Click Create a webhook. For information about webhooks, see Webhooks.
5. Enter a name for the webhook.
6. Select the Status as Enabled.
7. In the URL field, paste the URL copied from Agentspace and append /{issue.id}.

8. In the Secret field, enter the same value you entered when generating a webhook URL in Agentspace.

   

9. In the Issue related events section, select the following options:

   Entities	Created	Updated	Deleted
   Issue	Yes	Yes	Yes
   Worklog	Yes	Yes	Yes
   Comment	Yes	Yes	Yes
   Attachment	Yes	No	Yes

   

10. In the Project related events section, select the created, updated, and deleted checkboxes for the Project entity.

11. Click Create.

Error messages

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

Known limitations

• For unstructured data, each media type has different restrictions. For more information, see Prepare data for custom data sources.

• For structured data, each document must not exceed 500 KB in size.

• Application roles with specific, non-empty roles are not supported when granting "Browse project" or security level permissions.

• Document permissions determined by user custom fields or group custom fields are not supported.

• Jira Cloud does not allow any restrictions on worklog levels.

• Attachments added to private comments don't inherit the access restrictions (ACLs) on the comments.

• Only the previous 20 comments for an issue in Jira Cloud are fetched.

• The legacy user management model is not supported for integration with Jira Cloud. Only the centralized user management model is supported. For more information, see Atlassian Organization consolidation guide.

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.