Atlassian Integration

Connect your Atlassian Cloud site to give AI agents native Jira issue management and Confluence knowledge base capabilities through a single OAuth connection.

Overview

The Atlassian Integration enables your AI agents to interact with Jira and Confluence through 8 dynamic tools. Agents can search, create, update, and transition Jira issues, add comments, log work, and link issues. They can also search and read Confluence pages and create new pages for meeting notes, reports, and summaries.

The integration uses a single OAuth 2.0 authorization that covers both Jira and Confluence. After connecting, the system automatically discovers your projects, issue types, custom fields, priorities, and Confluence spaces, then enriches tool descriptions with this schema data so the LLM knows exactly what is available.

info

Jira tools support both read and write operations. Confluence tools support read and create. Editing existing Confluence pages is not supported in this version.

Use Cases

• Issue Triage from Email - Agent receives a bug report email, creates a Jira issue with appropriate project, type, and priority, then responds with the issue key
• Sprint Status Check - Agent searches open sprint issues using JQL and summarizes progress by status category
• Issue Update from Conversation - Agent transitions issues and adds comments based on chat messages or email instructions
• Knowledge Base Lookup - Agent searches Confluence for policies, procedures, or documentation and presents relevant answers
• Meeting Notes Creation - Agent creates Confluence pages with structured meeting notes in the appropriate space

How It Works

OAuth Connection          Schema Discovery          Agent Tools
        |                        |                       |
        v                        v                       v
+-----------------+       +-----------------+     +-----------------+
| Admin authorizes|  ->   | Auto-discover   | ->  | 8 tools created |
| via Atlassian   |       | projects, issue |     | with schema-    |
| OAuth 2.0 (3LO)|       | types, fields,  |     | enriched        |
|                 |       | spaces          |     | descriptions    |
+-----------------+       +-----------------+     +-----------------+

When you connect your Atlassian Cloud site via OAuth, the system discovers available products (Jira, Confluence, or both) and caches your schema. Up to 8 tools are created based on product availability - 5 Jira tools and 3 Confluence tools. Tool descriptions include your actual project names, issue types, priorities, and space names so the LLM can construct valid queries.

Getting Started

Prerequisites

Before connecting Atlassian:

1. Atlassian Cloud Account - You need an active Atlassian Cloud site (e.g., yourcompany.atlassian.net) with Jira and/or Confluence
2. Admin Access - You must have admin permissions on the Atlassian site to authorize the OAuth connection
3. Outermind Pro Plus+ - Atlassian integration requires the Pro Plus+ subscription tier
4. Cloud Only - On-premises Jira Server and Data Center deployments are not supported

warning

Only Atlassian Cloud is supported. If your organization uses Jira Server or Data Center, this integration will not work.

Step 1: Navigate to Atlassian Connection

1. Go to Build > Connections > Atlassian
2. You will see the Atlassian integration page with a summary of capabilities

Step 2: Connect Atlassian

1. Click Connect Atlassian to launch the setup wizard
2. Click the Connect to Atlassian button in the wizard
3. A popup opens redirecting you to Atlassian's authorization page
4. Sign in to your Atlassian account if prompted
5. Review the requested permissions and click Accept
6. The system automatically selects your Cloud site and detects available products (Jira, Confluence, or both)
7. You are returned to the setup wizard with your connection established

tip

The OAuth flow requests scopes for both Jira and Confluence. If your site only has one product enabled, only the corresponding tools will be created. No Atlassian credentials are stored in Outermind.

Step 3: Review Schema Discovery

After connecting, the system automatically discovers your site's schema:

• Projects with keys and names (e.g., ENG - Engineering, OPS - Operations)
• Issue Types per project (Bug, Task, Story, Epic, Sub-task, etc.)
• Custom Fields with names and types (Story Points, Sprint, Team, etc.)
• Priorities (Highest, High, Medium, Low, Lowest)
• Statuses per project and issue type (To Do, In Progress, Done, etc.)
• Confluence Spaces with keys and names

Schema discovery runs automatically in the background and typically completes within a few seconds. Tools are functional immediately, even before schema discovery finishes.

Step 4: Assign Tools to Agents

1. In the setup wizard's tool assignment step, select which tools to assign
2. Tools are grouped by product:
   • Jira Tools (5): search, get issue, create issue, update issue, manage issue
   • Confluence Tools (3): search, get page, create page
3. Assign tools to your AICOS agent and/or Personal Assistant agents
4. Click Complete to finalize the setup

You can also assign tools later through the standard agent configuration:

1. Go to Build > AI Agents > Agents
2. Edit the agent that should use Atlassian tools
3. In the Tools section, find the Atlassian tools
4. Enable the tools you want the agent to use
5. Save the agent

Managing Your Connection

Connection Details

Each connection displays:

Field	Description
Site Name	Your Atlassian Cloud site display name
Site URL	Your Atlassian Cloud URL (e.g., yourcompany.atlassian.net)
Products	Available products - Jira and/or Confluence with status indicators
Status	Current connection status (Active, Error, Token Expired)
Connected By	Email of the user who authorized the connection
Schema Last Refreshed	When the schema cache was last updated

Token Management

Atlassian access tokens have a short lifetime and are refreshed automatically:

• Access Token - Expires after 60 minutes (auto-refreshed transparently)
• Refresh Token - Long-lived, rotated on each refresh (no manual action required)

Token refresh happens automatically with distributed locking when an agent uses an Atlassian tool. If the refresh token becomes invalid (e.g., Atlassian app permissions changed or admin revoked access), you will need to reconnect.

Refresh Schema

Click Refresh Schema to manually trigger a fresh discovery of your site's projects, issue types, custom fields, priorities, statuses, and Confluence spaces. This is useful when you have made changes to your Atlassian configuration, such as:

• Creating new Jira projects
• Adding custom fields or issue types
• Changing workflow statuses
• Creating new Confluence spaces

info

Schema data is not automatically refreshed on a timer. When you make changes to your Jira or Confluence configuration, click Refresh Schema so your agents have up-to-date context. Tools remain functional even with stale schema data - the schema only enriches tool descriptions and input validation.

Disconnect

To disconnect your Atlassian site:

1. Click the Disconnect button
2. Confirm the disconnection in the dialog

warning

Disconnecting removes all Atlassian tools and their agent assignments. Agents will no longer be able to access Jira or Confluence. The OAuth token is revoked with Atlassian. You can reconnect at any time.

Schema Browser

The schema browser on the connection page displays your site's data model, giving you visibility into what your agents can work with.

Projects

Shows all Jira projects with their keys and names. For example:

ENG - Engineering
OPS - Operations
MKT - Marketing

Agents use project keys in JQL queries and when creating issues, so any changes to your projects should be followed by a schema refresh.

Issue Types

Displays the issue types available in each project. Issue types can vary by project:

Engineering (ENG)
 |- Bug
 |- Task
 |- Story
 |- Epic
 |- Sub-task

Operations (OPS)
 |- Bug
 |- Incident
 |- Task

Custom Fields

Lists all custom fields defined in your Jira instance with their internal IDs and data types:

Column	Description
ID	Internal field ID (e.g., customfield_10001)
Name	Display name (e.g., Story Points)
Type	Data type (number, string, option, etc.)

Priorities

Shows your Jira priority scheme. The default Atlassian priorities are Highest, High, Medium, Low, and Lowest, but custom priorities will also appear.

Statuses

Displays workflow statuses organized by project and issue type:

Engineering > Bug
 |- To Do (new)
 |- In Progress (indeterminate)
 |- In Review (indeterminate)
 |- Done (done)

Engineering > Task
 |- To Do (new)
 |- In Progress (indeterminate)
 |- Done (done)

Confluence Spaces

Lists all Confluence spaces with keys and names (up to 250 spaces):

ENG - Engineering
TEAM - Team Space
OPS - Operations

Available Tools

When you connect Atlassian, up to 8 tools are created based on product availability - 5 Jira tools and 3 Confluence tools.

1. Jira Search (atlassian_jira_search)

Search Jira issues using JQL with field selection and pagination.

Parameter	Required	Description
jql	Yes	JQL query string (e.g., project = ENG AND status = "In Progress")
fields	No	Comma-separated field names to return (default: summary, status, assignee, priority, issuetype, created, updated). Use *all for all fields
maxResults	No	Results per page (default: 25, max: 100)
startAt	No	0-indexed offset for pagination

Example uses:

• "Find all high-priority bugs in the Engineering project" - jql: project = ENG AND issuetype = Bug AND priority in (High, Highest)
• "What issues are in the current sprint?" - jql: sprint in openSprints() AND project = ENG ORDER BY status ASC
• "Search for checkout errors" - jql: text ~ "checkout error"

tip

JQL is passed directly to the Jira API, giving agents maximum query flexibility. Tool descriptions include your project keys and field names so the LLM can construct valid JQL without trial-and-error.

2. Jira Get Issue (atlassian_jira_get_issue)

Retrieve full details of a specific issue including description, comments, linked issues, and available transitions.

Parameter	Required	Description
issueKey	Yes	Issue key (e.g., "ENG-1234") or issue ID
expand	No	Comma-separated expansions: changelog, renderedFields, transitions (default: changelog,transitions)
fields	No	Comma-separated field names to return (default: all)

Example use: "Get the full details for ENG-1234 including comments and available transitions"

Returns core fields (summary, description as markdown, status, priority, assignee, reporter, labels), comments, subtasks, linked issues, available transitions, and recent changelog entries.

3. Jira Create Issue (atlassian_jira_create_issue)

Create a new Jira issue with configurable fields.

Parameter	Required	Description
projectKey	Yes	Project key (e.g., "ENG")
issueType	Yes	Issue type name (e.g., "Bug", "Task", "Story", "Epic")
summary	Yes	Issue title
description	No	Issue description in markdown (automatically converted to Atlassian Document Format)
assignee	No	Assignee display name or email (auto-resolved to Atlassian account ID)
priority	No	Priority name (e.g., "High", "Medium", "Low")
labels	No	Array of label strings
components	No	Array of component names
parentKey	No	Parent issue key for subtasks or children of epics
customFields	No	Object of custom field values keyed by field ID or name

Example use: "Create a high-priority bug in the Engineering project for the checkout page 500 errors and assign it to Sarah"

4. Jira Update Issue (atlassian_jira_update_issue)

Update existing issue fields and/or transition workflow status.

Parameter	Required	Description
issueKey	Yes	Issue key (e.g., "ENG-1234")
action	Yes	update_fields, transition, or both
fields	For update_fields/both	Object of field updates (summary, priority, labels, assignee, description)
transitionName	For transition/both	Target transition name (e.g., "In Progress", "Done", "In Review")
transitionComment	No	Comment to add during transition
customFields	No	Object of custom field values

Example use: "Move ENG-1234 to In Review and update the priority to High"

info

Transition names are resolved automatically to Jira transition IDs. If the requested transition is not available from the issue's current status, the tool returns an error listing the available transitions.

5. Jira Manage Issue (atlassian_jira_manage_issue)

Secondary operations: comments, worklogs, links, labels, assignment, and watchers.

Parameter	Required	Description
issueKey	Yes	Issue key (e.g., "ENG-1234")
action	Yes	add_comment, add_worklog, link_issues, add_labels, remove_labels, assign, unassign, or add_watcher
body	For add_comment	Comment text in markdown
timeSpent	For add_worklog	Duration in Jira format (e.g., "2h 30m", "1d")
worklogComment	For add_worklog	Description of work done
targetIssueKey	For link_issues	The other issue to link to
linkType	For link_issues	Link type (e.g., "blocks", "relates to", "duplicates")
labels	For add/remove_labels	Array of label strings
accountId	For assign/add_watcher	User display name or email (auto-resolved)

Example use: "Add a comment to ENG-1234 that the fix has been deployed to staging, and log 2 hours of work"

6. Confluence Search (atlassian_confluence_search)

Search Confluence pages and spaces using CQL (Confluence Query Language).

Parameter	Required	Description
cql	Yes	CQL query string (e.g., type = page AND space = "ENG" AND text ~ "deployment")
limit	No	Results per page (default: 25, max: 250)
cursor	No	Opaque cursor for pagination (from previous response)
includeBody	No	Include page body in results as markdown (default: false, caps results at 50)

Example uses:

• "Find pages about refund policy" - cql: type = page AND text ~ "refund policy"
• "Search for runbooks in the Operations space" - cql: type = page AND space = "OPS" AND label = "runbook"
• "Recent pages in the Team space" - cql: type = page AND space = "TEAM" ORDER BY lastmodified DESC

7. Confluence Get Page (atlassian_confluence_get_page)

Get full page content including body, labels, ancestors, and child pages.

Parameter	Required	Description
pageId	Yes	Confluence page ID (numeric string)
includeChildren	No	Include list of child pages (default: false)
includeAncestors	No	Include breadcrumb ancestor pages (default: true)

Example use: "Get the full content of the deployment process page"

Returns the page title, space, body (converted from Atlassian Storage Format to markdown), labels, ancestor breadcrumbs, child pages (if requested), and metadata.

8. Confluence Create Page (atlassian_confluence_create_page)

Create a new page in a specified Confluence space.

Parameter	Required	Description
spaceKey	Yes	Confluence space key (e.g., "ENG", "TEAM")
title	Yes	Page title
content	Yes	Page content in markdown (automatically converted to Atlassian Storage Format)
parentPageId	No	Parent page ID for creating nested pages (omit for space root)
status	No	current (published, default) or draft
labels	No	Array of label strings to apply

Example use: "Create a page in the Team space with today's standup notes as a child of the Weekly Meetings page"

Assigning Tools to Agents

After connecting Atlassian:

1. Go to Build > AI Agents > Agents
2. Edit the agent that should use Atlassian tools
3. In the Tools section, find the Atlassian tools
4. Enable the tools appropriate for the agent's role
5. Save the agent

tip

Recommended tool assignments by agent type:

• Research/read-only agents - Enable atlassian_jira_search, atlassian_jira_get_issue, atlassian_confluence_search, and atlassian_confluence_get_page for read-only access
• Operations agents - Enable all 8 tools for full Jira and Confluence management
• Email agents - Enable search and get tools for context-aware email handling, plus create tools for automated issue creation from emails

Rate Limiting

Atlassian tools include built-in rate limiting to protect your site:

Limit Type	Value	Scope
Hourly points	65,000+ points/hour	Per OAuth app
Burst (GET)	100 requests/second	Per OAuth app
Burst (POST)	100 requests/second	Per OAuth app
Burst (PUT/DELETE)	50 requests/second	Per OAuth app
Per-issue writes	20 writes per 2 seconds	Per issue

The integration handles rate limiting automatically:

• 429 responses trigger automatic retry with exponential backoff (up to 4 attempts)
• Retry-After headers are respected when present
• Schema caching reduces API calls by storing project, field, and space data locally

Troubleshooting

Connection Fails

Problem: OAuth authorization does not complete

Solutions:

1. Verify you are signed in to Atlassian as an admin
2. Check that your Atlassian Cloud site is active
3. Ensure pop-up blockers are not preventing the OAuth redirect
4. Confirm you are using Atlassian Cloud (not Server or Data Center)
5. Try again in a private/incognito browser window

Token Expired

Problem: Atlassian tools return authentication errors

Solutions:

1. Token refresh is automatic; wait a moment and retry
2. If refresh fails, navigate to Build > Connections > Atlassian and check the connection status
3. If status shows "Token Expired", click Disconnect and reconnect via OAuth

Schema Not Showing New Projects or Spaces

Problem: Recently created Jira projects or Confluence spaces do not appear in tool descriptions

Solutions:

1. Click Refresh Schema to trigger a fresh discovery
2. Schema is not automatically refreshed on a timer - manual refresh is required after configuration changes
3. Tools still function even with stale schema data; the LLM can use JQL/CQL to query projects not in the cache

Rate Limit Exceeded

Problem: Agents receive rate limit errors

Solutions:

1. The system retries automatically with backoff; most rate limit issues resolve on their own
2. If persistent, reduce the number of agents using Atlassian tools simultaneously
3. Review agent instructions to minimize unnecessary queries
4. Schema data is cached to reduce API calls; avoid frequent manual schema refreshes

Agent Cannot Find Atlassian Tools

Problem: Atlassian tools do not appear when editing an agent

Solutions:

1. Verify the Atlassian connection is active at Build > Connections > Atlassian
2. Confirm the connection status shows "Active" (not "Error" or "Disconnected")
3. Refresh the page
4. If you recently connected, wait a moment for tool creation to complete

Invalid JQL or CQL Errors

Problem: Agent receives query syntax errors

Solutions:

1. JQL and CQL are passed directly to the Atlassian API - syntax errors return clear messages
2. Refresh the schema so tool descriptions include current project keys and field names
3. Review agent instructions to include JQL/CQL examples for common queries
4. Check that field names and project keys match your Jira/Confluence configuration exactly

Confluence Tools Unavailable

Problem: Only Jira tools are created, Confluence tools are missing

Solutions:

1. Check the connection details for the "Products" section - Confluence may not be available on your Atlassian site
2. If Confluence was recently enabled on your site, disconnect and reconnect to re-detect available products
3. Product detection happens at connection time and is not re-evaluated automatically

Security

Data Protection

• OAuth 2.0 (3LO) authorization with Atlassian (no credentials stored)
• Tokens encrypted with AES-256-CBC at rest
• Automatic token refresh every 60 minutes with distributed locking
• Refresh tokens rotated on each use
• Tenant isolation ensures each customer's Atlassian site is separate
• Token revocation on disconnect

Access Control

Atlassian tools enforce tiered access controls through the agent authorization system:

AICOS (Chief of Staff) Access:

Tool	Minimum Auth Level	Who Can Trigger
atlassian_jira_search	Internal	Employees from verified business domains
atlassian_jira_get_issue	Internal	Employees from verified business domains
atlassian_jira_create_issue	VIP	VIP contacts and business owners only
atlassian_jira_update_issue	VIP	VIP contacts and business owners only
atlassian_jira_manage_issue	VIP	VIP contacts and business owners only
atlassian_confluence_search	Internal	Employees from verified business domains
atlassian_confluence_get_page	Internal	Employees from verified business domains
atlassian_confluence_create_page	VIP	VIP contacts and business owners only

Personal Assistant Access:

All 8 tools require Internal tier (employees are internal by definition).

info

External senders cannot trigger any Atlassian tool. Read tools are restricted to internal users (verified business domain). Write tools in AICOS are further restricted to VIP-level senders to prevent lower-priority internal senders from creating issues or pages without escalation.

Audit Logging

Every Atlassian tool execution is recorded in the agent execution log, including:

• Tool name and action performed
• Parameters used (JQL/CQL queries, issue keys, project keys)
• Execution duration and result status
• Associated agent and execution ID

Best Practices

Agent Instructions

Help your agents use Atlassian tools effectively by including guidance in their instructions:

When working with Jira:
1. Use atlassian_jira_search with JQL to find issues before making changes
2. Use atlassian_jira_get_issue to get full details and available transitions
3. When creating issues, always specify project, issue type, summary, and priority
4. Check for duplicates before creating new issues

When working with Confluence:
1. Use atlassian_confluence_search with CQL to find relevant pages
2. Use atlassian_confluence_get_page to read full page content
3. When creating pages, choose the appropriate space and parent page
4. Add relevant labels to new pages for discoverability

Schema Refresh

• Refresh schema after creating new Jira projects or issue types
• Refresh schema after adding custom fields
• Refresh schema after creating new Confluence spaces
• Schema refresh is manual - refresh when your Atlassian configuration changes

Tool Assignment Strategy

• Start with read-only tools (atlassian_jira_search, atlassian_jira_get_issue, atlassian_confluence_search, atlassian_confluence_get_page) and add write tools as needed
• Assign atlassian_jira_manage_issue to agents that handle post-meeting follow-ups or issue commenting
• Assign atlassian_confluence_create_page to agents that generate reports or meeting summaries
• Use atlassian_jira_create_issue for agents that triage incoming emails or chat messages into Jira tickets

Related Topics

• Tools Overview - All available agent tools
• Agents - Configure agents to use tools
• HubSpot CRM Integration - Another OAuth integration with schema discovery
• Agent Executions - View tool execution logs