# Atlassian Agent

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><strong>Overview</strong></td><td><ul><li>Search and retrieve Jira issues and Confluence pages through Blockbrain</li><li>Create, update, and manage Jira tasks, issues, and projects</li><li>Extract and summarize content from Confluence spaces and pages for reporting or AI analysis</li><li>Access project, issue, and page metadata for enhanced workflow automation</li><li>Automate processes and reporting across Jira and Confluence using Atlassian data</li></ul></td><td><a href="/files/ikR2AL5octrVSvEocI7Z">/files/ikR2AL5octrVSvEocI7Z</a></td></tr><tr><td><strong>Prerequisites</strong></td><td><ul><li>Complete the <a href="https://docs.en.theblockbrain.ai/for-users/agents">general setup steps</a> from the main AI Agents page</li><li>Ensure users have active Atlassian Cloud accounts with access to Jira and/or Confluence</li><li>Verify appropriate Atlassian product licensing for Jira and Confluence</li></ul></td><td><a href="/files/X7MpGP1nVARHAWPFype1">/files/X7MpGP1nVARHAWPFype1</a></td></tr></tbody></table>

### Atlassian App Registration Configuration

#### Required API Permissions

Add the following Atlassian API permissions (OAuth 2.0 scopes) to your app registration:

<table><thead><tr><th width="352">Permission</th><th width="171">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>offline_access</code></td><td>Delegated</td><td>Maintain access to data you have given it access to</td></tr><tr><td><code>read:confluence-space.summary</code></td><td>Delegated</td><td>View summary information about Confluence spaces</td></tr><tr><td><code>read:confluence-props</code>     </td><td>Delegated</td><td>View Confluence content properties</td></tr><tr><td><code>read:confluence-content.all</code> </td><td>Delegated</td><td>View all Confluence content (pages, blogs, etc.)</td></tr><tr><td><code>read:confluence-content.summary</code></td><td>Delegated</td><td>View summary information about Confluence content</td></tr><tr><td><code>read:confluence-content.permission</code></td><td>Delegated</td><td>View permissions for Confluence content</td></tr><tr><td><code>read:confluence-user</code></td><td>Delegated</td><td>View Confluence users</td></tr><tr><td><code>read:confluence-groups</code></td><td>Delegated</td><td>View Confluence groups</td></tr><tr><td><code>readonly:content.attachment:confluence</code></td><td>Delegated</td><td>View attachments in Confluence content</td></tr><tr><td><code>search:confluence</code></td><td>Delegated</td><td>Search Confluence content</td></tr><tr><td><code>read:jira-work</code></td><td>Delegated</td><td>Read access to Jira issues, projects, workflows, and work items</td></tr><tr><td><code>read:jira-user</code></td><td>Delegated</td><td>View Jira users and their profiles for assignment operations</td></tr><tr><td><code>read:project:jira</code></td><td>Delegated</td><td>Read access to Jira project details, configurations, and metadata</td></tr><tr><td><code>read:board-scope:jira-software</code></td><td>Delegated</td><td>View Jira Software boards, sprints, and agile project data</td></tr><tr><td><code>write:jira-work</code></td><td>Delegated</td><td>Create, edit, update, and manage Jira issues and work items</td></tr></tbody></table>

> As alternative, you can use the `.default` scope (uses all scopes set in the app).

{% hint style="info" %}
**Scope clarification**: The Atlassian Agent connects to two products with distinct permission requirements:

* **Jira**: Requires specific Read & Write scopes to enable comprehensive issue operations (create, edit, assign, transition, search). Configure the granular Jira scopes listed in the permissions table above for optimal functionality.
* **Confluence**: Uses read-only access for search and content retrieval. Configure only the Confluence read scopes listed above (no write scopes needed).

**Recommendation**: Configure both Jira and Confluence scopes as listed in the permissions table, or use the `.default` scope for comprehensive access to both products.
{% endhint %}

#### Redirect URL

* Add <https://nango.theblockbrain.ai/oauth/callback> as allowed redirect URL to your app registration

#### Permission Configuration Steps

1. In your Atlassian developer console, go to your app’s **OAuth 2.0 (3LO) configuration**
2. Click **"Add scopes"**
3. Search for and select each required permission scope (see table above)
4. Click **"Add"** to include the selected scopes in your app
5. Save your changes
6. (Recommended) Have an Atlassian admin grant consent for all required scopes for organization-wide deployment

### Agent Configuration in Blockbrain

<div data-with-frame="true"><figure><img src="/files/y4tERjHqH3WDUrG41rOn" alt=""><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/1jlcXcKaaDcITNRWvX6W" alt=""><figcaption></figcaption></figure></div>

<figure><img src="/files/SBdQZaCXQLxPNKluJcSK" alt=""><figcaption></figcaption></figure>

1. **Access Agent Settings**:
   * Navigate to your Blockbrain admin panel
   * Go to **Agents** > **Atlassian Agent**
   * Click **"Configure"**
2. **Enter Atlassian OAuth Credentials**:
   * **Client ID**: Enter the Client ID from your Atlassian OAuth app
   * **Client Secret**: Paste the client secret you generated
   * **Redirect URL**: Verify `https://nango.theblockbrain.ai/oauth/callback` is configured
3. **Configure Dual Integration Connectors**:
   * The Atlassian Agent includes **two separate connectors**:
     * **Jira Connector**: For issue management and project operations
     * **Confluence Connector**: For documentation search and content retrieval
   * **Configure each connector individually** in the admin interface
   * **Important**: Both connectors must be visible and configured for full functionality
4. **Configure OAuth Scopes**:
   * Add required scopes for both Jira and Confluence using the **"Add"** button as mentioned [here](#required-api-permissions)
   * Each scope will appear as a removable tag
   * Use the **"X"** button to remove incorrect scopes
5. **Additional Configuration** (Optional):
   * Add custom key-value pairs if needed for specific requirements
   * Configure any organization-specific settings
6. **Save Configuration**:
   * Click **"Save"** to apply the settings
   * Wait for the confirmation message
   * **Verify both Jira and Confluence connections are active**

### Alternative: Admin Consent Configuration

For simplified scope management with admin pre-approval:

1. In the Atlassian Developer Console, have an admin grant consent for all required permission scopes
2. In Blockbrain configuration, use the `.default` scope instead of individual scopes
3. This eliminates the need for users to consent to individual permissions

### Testing the Atlassian Agent

#### Verification Steps

1. **Connection Test**:
   * Use the built-in connection test in Blockbrain
   * Verify successful authentication with the Atlassian API
2. **User Testing**:
   * Have a test user connect their Atlassian account
   * Attempt to access a known Jira issue or Confluence page
   * Verify issue/page retrieval and search functionality
3. **Permission Validation**:
   * Check that the agent can access the appropriate Jira projects and Confluence spaces
   * Confirm read/write permissions are working correctly

### Common Atlassian Integration Use Cases

* **Issue Search**: Find Jira issues across multiple projects
* **Content Extraction**: Access and summarize Confluence pages for AI analysis
* **Project Navigation**: Browse Jira project structures and Confluence spaces
* **Metadata Retrieval**: Retrieve issue properties, page metadata, and comments

### Troubleshooting

#### Authentication Issues

**Problem**: "Access denied" or authentication failures

* **Solution**: Verify admin consent is granted for all required Atlassian API permissions scopes
* **Check**: Ensure the redirect URL is exactly `https://nango.theblockbrain.ai/oauth/callback`

#### Permission Errors

**Problem**: "Insufficient privileges" when accessing Jira or Confluence

* **Solution**: Confirm the app registration has all necessary Jira and Confluence API scopes
* **Check**: Verify the user has access to the relevant projects and spaces in your Atlassian organization

#### Scope Configuration Issues

**Problem**: Scopes not saving correctly

* **Solution**: Add each scope individually using the "Add" button
* **Check**: Remove any duplicate or incorrect scopes using the "X" button

### Security Considerations

* **Data Access**: The agent inherits the user's Atlassian permissions
* **Project/Space Scope**: Access is limited to projects and spaces the authenticated user can access
* **Data Privacy**: Data is processed according to Blockbrain's data handling policies
* **Audit Trail**: Atlassian access is logged in both Atlassian Cloud and Blockbrain audit logs

### Next Steps

After successful Atlassian Agent configuration:

* **User Training**: Train users on both Jira and Confluence integration features
* **Permission Review**: Regularly audit user access to ensure appropriate Atlassian permissions
* **Integration Monitoring**: Monitor both connectors for ongoing functionality
* **Feature Adoption**: Encourage teams to leverage cross-platform capabilities (Jira-Confluence linking)
* **Support Documentation**: Share common use cases and troubleshooting guides with end users


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blockbrain.ai/for-admins/agents/atlassian-agent.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.