Connect Jira Cloud

This page describes how to connect Jira Cloud to Agentspace Enterprise.

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 setting up your connection:

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

  • Set up access control. Verify that access control is properly configured for your data source. This step verifies that only authorized users can access and manage the data. For more information, see Identity and permissions.

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

select
Settings

Create an OAuth 2.0 integration

  1. Sign in to the Atlassian Developer Console.

  2. Click the profile icon and select Developer console.

    select
    Select Developer console

  3. Click Create and select OAuth 2.0 Integration.

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

    select
    Create a new OAuth 2.0 Integration

  7. Click Authorization.

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

    select-add
    Add authorization type

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

  10. Click Save changes.

    select
    Save changes

Configure the minimum permissions required for the application

  1. On the application page, click Permissions.

    select
    Select Permissions

  2. Go to Jira API and click Add. Note: After adding the Jira API, the Configure button may take a moment to appear. If it does not show up immediately, try refreshing the page or waiting a few seconds.

  3. Click Configure.

  4. Go to the Classic scopes tab.

  5. Click Edit scopes and select the following permissions:

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

    select
    Edit Classic scopes

  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
    • read:board-scope.admin:jira-software
    • read:board-scope:jira-software
    • read:epic:jira-software
    • read:issue-details:jira
    • read:jql:jira
    • read:project:jira

    select
    Edit Granular scopes

Minimum permissions

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

Classic scopes

Permission Usage reason Description
read:jira-work Data ingestion Allows the connector to read details of entities (including issues, attachments, comments, and properties).
read:jira-user Enforce Access Control Lists (ACLs) Allows the connector to read user and group details.

Granular scopes

Permission Usage reason Description
read:issue-security-level:jira Enforce ACLs Enables enforcement of ACLs for issues based on their specific issue security levels.
read:issue-security-scheme:jira Enforce ACLs Enables enforcement of ACLs for issues based on their associated issue security schemes.
read:group:jira Enforce ACLs Allows the connector to read group information in order to enforce ACLs related to group memberships.
read:user:jira Enforce ACLs Allows the connector to read user information in order to enforce ACLs related to individual user permissions.
read:avatar:jira Enforce ACLs Allows the connector to read user and group information to enforce ACLs. Avatar is not used, but is part of the granular scopes that are bundled with groups and users.
read:audit-log:jira Monitor ACLs Allows the connector to read Jira's audit log for ACL verification and monitoring.
read:board-scope.admin:jira-software Data ingestion Allows the connector to read comprehensive board configurations and details, including administrator-level insights into board filters and settings.
read:board-scope:jira-software Data ingestion Allows the connector to read board details, such as columns, swimlanes, and general board configurations, as visible to standard users.
read:epic:jira-software Data ingestion Allows the connector to read epic specific information, including epic names, summaries, and associated issues.
read:issue-details:jira Data ingestion Allows the connector to read all details of Jira issues, including fields, comments, attachments, and work logs.
read:jql:jira Data ingestion Allows the connector to read and execute Jira Query Language (JQL) queries.
read:project:jira Data ingestion Allows the connector to read project-level information, including project names, keys, categories, and associated metadata.

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.
      select
      Edit Distribution

    5. Click Save changes.

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

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

        select
        Obtain 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).

    Set up user visibility and roles

    To set the user visibility, do the following:

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

      manage-account
      Manage account

    2. Navigate to the Profile and visibility.

      profile-visibility
      Profile and visibility

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

      contact
      Contact

    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.
    3. Locate the Jira administrator account.
    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.

      manage-users
      Manage users

    4. Click Groups under User management.

    5. On the Groups page:

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

      create-group
      Create 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.

      jira-user-access-admin
      Jira user access administrator

    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.

      add-group-members
      Add group members

    Create a Jira Cloud connector

    Console

    To use the Google Cloud console to sync data from Jira Cloud to Agentspace Enterprise , follow these steps:

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

      Agentspace

    2. In the navigation menu, click Data Stores.

    3. Click Create data store.

    4. On the Select a data source page, scroll or search for Jira Cloud to connect your third-party source and click Select.

    5. In the Authentication settings section, enter the Instance URI, Instance ID, Client ID, and Client secret.

    6. Click Login.

    7. Select the site on which the app will be used, and click Accept.

    8. Click Continue.

    9. In the Advanced options section:

      • Optional. To allow a set of static IP addresses in your system, select Enable Static IP Addresses for registration.

      • Optional. To synchronize data, select a date in Sync since. This syncs data from the chosen date forward. If no date is selected, all available historical data is synced.

      • Optional. To apply a rate limit on the queries that the connector sends to the Jira Cloud instance, in the Max QPS field, specify the maximum queries per second. The default value is 12 QPS.

      • Click Continue.

    10. In the Entities to sync section:

      1. Select the entities you want to sync from the following:

        • Attachment

        • Comment

        • Issue

        • Worklog

      2. Click Continue.

    11. Select the Sync frequency for Full sync and the Incremental sync frequency for Incremental data sync. For more information, see Sync frequency.

      If you want to schedule separate full syncs of entity and identity data, expand the menu under Full sync and then select Custom options.

      Custom options for full data sync.
      Setting separate schedules for full entity sync and full identity sync.

    12. In the Configure your data connector section:

      1. Select a region for your data store. You cannot change the region later. For more information on multi-regions, see AI Applications locations.

      2. Enter a name for your data connector. You can change the name later.

      3. Optional. To change the data connector ID after entering the name, click Edit and change the value. You cannot change the data connector ID after creating the data store.

      4. Click Create. Agentspace Enterprise creates your data store and displays it on the Data Stores page.

    To check the status of your ingestion, go to the Data stores page and click your data store name to see details about it on its Data page. The Connector state changes from Creating to Running when it starts synchronizing data. When ingestion is complete, the state changes to Active to indicate that the connection to your data source is set up and awaiting the next scheduled synchronization. Depending on the size of your data, ingestion can take several minutes or several hours.

    For detailed information on quotas, including default limits and instructions to request higher quotas, see the Quotas and limits.

    Error messages

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

    Error code Error message Description Troubleshooting
    JIRA_INVALID_AUTH_1 OAuth setup failed. A token refresh call encountered a problem, possibly related to credentials, the secret manager, or connectivity. Exception details are provided in the full error message. Possible causes and solutions include:
    • Connectivity issues: These generally resolve through internal retries.
    • Invalid credentials: Verify or correct the credentials.
    JIRA_INVALID_AUTH_2 Authentication failed. The connector cannot authenticate with Jira Cloud because the user account lacks sufficient API access. Re-authenticate the datastore using administrator credentials.
    JIRA_MISSING_PERMISSION_1 Non-admin users are not authorized to get the issue security schemes. A user account without administrator privileges attempted to retrieve the issue security schemes. Grant the necessary administrator permissions to the user account.
    JIRA_MISSING_PERMISSION_2 Non-admin users cannot get permission schemes. A user account without administrator privileges attempted to retrieve permission schemes. Grant the necessary administrator permissions to the user account.
    JIRA_MISSING_PERMISSION_3 Problem while fetching project permissions. A user account without administrator privileges attempted to retrieve project details. Grant the necessary administrator permissions to the user account.
    JIRA_IO_CONNECTION Problem while connecting to Jira. The connector fails to connect to your Jira Cloud instance, indicating a general inability to establish or maintain communication with the Jira server. Verify your Jira URL and cross check your authentication credentials. Verify your Jira instance is operational and your API token or OAuth scopes grant the necessary permissions.
    JIRA_INVALID_BOARD_LOCATION Board location is invalid. Either project key or user account ID should be present as location for board. A Jira board was created without a specified location, typically through API usage. Jira boards without locations are not supported. Ensure that either a projectKey or a user account ID is specified as the board location.

    Known issues

    • Boards without specified locations are not supported. You must provide a projectKey or a user account ID as the location of the board.

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

    • 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