JIRA integration
📋 JIRA Integration
"Connect issue tracking to your GRC workflow — browse, create and manage JIRA issues from Brainframe, and link them to any document as live tasks."
Use Atlassian API credentials to search your JIRA Cloud site, work on issues in Brainframe, and tie remediation or project work directly to risks, controls, audits and compliance records.
The JIRA integration connects Brainframe to your Atlassian JIRA Cloud site through the JIRA REST API (API token authentication). Once configured, you can search and manage issues from the integrations area — and, more importantly, link or import JIRA issues as tasks on documents and in folders, alongside other task integrations such as Asana, Monday.com, Azure DevOps and SolarWinds Service Desk.
1️⃣ Before You Begin
To configure the integration you will need:
- 🛠 A Brainframe account with permission to save credentials (see Credential scope below).
- 🔐 An Atlassian account with access to the JIRA Cloud site you want to connect (e.g.
yourcompany.atlassian.net). - 🎫 A JIRA API token created for that Atlassian account at Atlassian API tokens.
- 📂 Sufficient JIRA permissions in your projects to browse, create and edit the issues you expect to use (typically Browse projects, Create issues, Edit issues — exact names depend on your JIRA permission scheme).
⚠️ Brainframe uses JIRA Cloud REST API v3. Server/Data Center sites with a custom base URL are not supported by the current integration model, which expects an *.``atlassian.net (or equivalent Cloud) domain.2️⃣ Configure the Integration
Step 1 — Create an API token in Atlassian
- Log in to your Atlassian account.
- Open Atlassian API tokens.
- Click Create API token, give it a label (e.g.
Brainframe GRC), and copy the token immediately. - Note the email address of the Atlassian account that owns the token — this is required for Basic authentication against the JIRA API.
📌 The token inherits the JIRA permissions of that Atlassian user. Use a service account with appropriate project access if you want workspace-wide, non-personal behaviour.
Step 2 — Enter credentials in Brainframe
Go to Workspace Settings → Integrations → JIRA → Configure (/integrations/jira/config).
Fill in:
Field | Description |
|---|---|
JIRA domain | Your site hostname, e.g. |
The Atlassian account email that owns the API token. | |
API token | The token you created. Encrypted at rest; never returned to the browser after saving. |
Then click Save configuration. Brainframe validates the credentials against GET /rest/api/3/myself before storing them.
📌 If no credentials exist yet, opening JIRA Issues redirects you to this configuration page automatically.
Credential scope
Brainframe supports two credential models:
Scope | Who can configure | Who can use |
|---|---|---|
Individual | Any user | Only that user (their own token) |
Workspace | Workspace administrators only | Everyone in the workspace (token stays on the server) |
Individual credentials take priority over workspace credentials when both exist for the same user.
📌 Workspace scope is ideal for a shared service account. Individual scope suits consultants or users who connect their own JIRA identity.
3️⃣ Using the JIRA Integration Page
Open Workspace Settings → Integrations → JIRA (or the Integrations sidebar menu when JIRA is enabled for your workspace).
The gear icon opens credential configuration. New issue opens the create form.
🔎 Search and filters
The issue browser builds a JQL query from your filters:
Control | Behaviour |
|---|---|
Search | Matches summary or description (text search). Press Enter or click the search button. |
Project | Restrict to one project, or All projects. |
Type | Issue type filter (Task, Bug, Story, …). |
Priority | Priority filter. |
Clear | Resets all filters. |
Refresh | Reloads the current result set. |
When no filter is applied, Brainframe adds a default recency bound: updated >= -90d ORDER BY updated DESC. This keeps large tenants responsive. Use search or project filters to reach older issues.
Results show Showing X of Y issues with Load more pagination (50 issues per page).
📊 Issue table
Column | Content |
|---|---|
Key | Issue key (e.g. |
Summary | Issue title. |
Status | Workflow status (colour-coded badge). |
Priority | Priority name. |
Type | Issue type. |
Project | Project name. |
Assignee | Current assignee display name. |
Updated | Last update date. |
↗ | Open in JIRA — opens the issue in Atlassian in a new tab. |
➕ Create, view, edit and delete
Action | Where |
|---|---|
Create | New issue on the integration page, or New issue inside the integrations browser dialog. |
View | Click a row, or open a linked/imported document that points to |
Edit | Edit on the issue detail page or inline document view — summary, description (markdown), priority, assignee, status (via workflow transition). |
Delete | Delete on the issue detail page — removes the issue in JIRA (and optionally archives the Brainframe document when opened inline). |
Create / edit fields
Field | Required | Notes |
|---|---|---|
Project | Yes (create) | Project key. |
Issue type | Yes (create) | Defaults to Task when available. |
Summary | Yes | Also synced to the Brainframe document title when |
Description | No | Markdown in Brainframe; converted to/from JIRA ADF. |
Priority | No | From your JIRA priority scheme. |
Assignee | No | Searchable JIRA users. |
Status | Edit only | Changed via allowed workflow transitions, not free text. |
⚠️ Description editing limitations
JIRA stores rich descriptions as Atlassian Document Format (ADF). Brainframe can edit plain text and simple markdown safely. If the description contains unsupported ADF nodes — images, tables, macros, panels, etc. — Brainframe shows an Editing is disabled warning and blocks in-app edits until you simplify the content in JIRA.
💡 Line breaks in descriptions are preserved when viewing and editing supported content.
4️⃣ Task Integrations — Linking Work to Documents
Beyond the standalone JIRA page, Brainframe treats JIRA as a task integration: you can attach external work items to GRC documents without leaving your compliance context.
Task integrations in Brainframe today include:
Integration | Badge | Typical use |
|---|---|---|
JIRA | Tasks | Issue tracking, remediation tickets, audit actions |
Asana | Tasks | Project tasks |
Tasks | Work management items | |
Azure DevOps | Tasks | Work items, user stories, bugs |
SolarWinds Service Desk | Tasks / Incidents / Assets | ITSM tickets and records |
All of these are reachable through the same Add from integrations / Task from integrations browser. JIRA is filtered under the Tasks category.
Two modes: Link vs Import
Mode | Purpose | Result |
|---|---|---|
Link | Attach a task to the document you are working on | Creates an Action document linked as a child task; stores |
Import | Add records into a folder (like any other document) | Creates document(s) in the folder you choose; optional bulk selection with checkboxes. |
The browser title is Add from integrations. When linking from a document, the catalog is pre-filtered to Tasks integrations only.
5️⃣ Document Bolt Icon — Task from integrations
On any open document, the bolt (⚡) menu in the document header provides quick actions:
Menu item | Action |
|---|---|
Create task in Brainframe | Adds a native Brainframe task in the Activities / Tasks panel. |
Request document review | Starts a document review workflow. |
Record that the actions… (tracker documents only) | Marks daily tracker completion. |
Task from integrations | Opens the integrations browser in link mode, filtered to Tasks. |
Workflow — link a JIRA issue to the current document
- Open a document (risk, control, audit finding, policy, etc.).
- Click the bolt icon → Task from integrations.
- Select JIRA from the catalog (or another task integration).
- Search for an existing issue, or click New issue to create one in JIRA.
- Click Link on the issue row.
Brainframe then:
- Creates an Action task document with the issue summary as title.
- Sets
brainframeIntegrationUrlto/integrations/jira/view/{issueKey}. - Relates that task to your document in the Tasks / Activities panel.
- Refreshes task links so the new item appears immediately.
The same entry point exists on the Tasks panel ADD menu (Task from integrations) when you expand Activities on a document.
📌 Task from integrations requires a saved document in a folder context. Save the document first if you opened it from the inbox or before the context is known.
Opening a linked JIRA task from the document opens the inline JIRA viewer inside the document editor — live status, description, edit and Open in JIRA without navigating away from your GRC record.
6️⃣ NEW Menu and Table View — Add from integrations
You can also bring JIRA issues (and other integration records) into a folder without linking them to a specific parent document.
Folder view — NEW dropdown
In any folder, open the NEW menu (plus button):
- Choose Add from integrations (cloud icon).
- The integrations browser opens in import mode with the full catalog.
- Select JIRA, search or create issues, then Import (or bulk-import with checkboxes).
- Pick the target folder and document type in the folder selection step.
Other NEW menu items (upload, subfolder, document types, asset wizard, etc.) are unchanged — Add from integrations is the unified replacement for the older per-provider cloud submenu.
Table view — cloud button
In a table view (document type table for a folder), the toolbar includes a cloud button:
- Tooltip: Add from integrations
- Opens the same browser in import mode.
- Pre-selects the current table’s document type in the import dialog when applicable.
Use this to populate a table of linked JIRA-backed actions, remediation tickets, or any imported type you choose.
Inside the JIRA browse step (import or link)
Action | Import mode | Link mode |
|---|---|---|
Search | Find issues (default: updated in last 90 days). | Same |
Import / Link | Per-row button; bulk toolbar for multi-select. | Link only (no checkboxes). |
Open | Opens issue in JIRA (new tab). | Same |
New issue | Creates in JIRA, then imports or links automatically based on mode. | Same |
Configure (admin) | Shortcut to JIRA credential settings if not configured. | Same |
After import, documents live in the chosen folder like any other Brainframe document. After link, they appear under the parent document’s Tasks list.
7️⃣ Sidebar Integrations Menu
When an integration is configured and enabled for your user/group, it appears under the workspace Integrations sidebar menu (alphabetically among enabled integrations).
- JIRA opens
/integrations/jira— the issue browser described in section 3. - Greyed-out entries mean the integration is visible in the menu configuration but not enabled or not accessible for your user — ask an administrator to enable it under Workspace Settings → Menu interface.
Configuration remains at Integrations → JIRA → Configure (admin for workspace scope; any user for individual scope).
8️⃣ Permissions Summary
Action | Requirement |
|---|---|
Save workspace JIRA credentials | Workspace administrator |
Save individual JIRA credentials | Any authenticated user |
Browse / create / edit / delete JIRA issues | Valid credentials (individual, workspace, or legacy) + JIRA project permissions for the API user |
Task from integrations (link) | Document saved in a folder; user can create documents and relations |
Add from integrations (import) | Write access to target folder |
Integrations sidebar menu item | Integration enabled in menu config + catalog status available + user/group access |
📌 Brainframe never exposes API tokens to the browser after save. All JIRA API calls are proxied through the Brainframe backend.
9️⃣ Tips for GRC Use Cases
Scenario | Suggested approach |
|---|---|
Remediation ticket on a risk or finding | Open the risk document → bolt → Task from integrations → JIRA → link or create issue. |
Audit action tracker | Table view of Action documents → import linked JIRA issues into the audit folder. |
Control testing follow-up | Link JIRA tasks to control documents; reviewers see live status inline. |
Project-wide issue triage | Use Integrations → JIRA to search/filter, then import selected issues into a compliance project folder. |
Personal vs shared connection | Use individual credentials for your own JIRA user; workspace credentials for a shared bot/service account. |
🔟 Troubleshooting
Symptom | Likely cause | What to do |
|---|---|---|
Redirected to Configure JIRA | No credentials for your user/workspace | Save individual or workspace credentials; or confirm legacy integration exists. |
Failed to load JIRA issues | Invalid token, wrong domain/email, or revoked token | Regenerate API token; re-save configuration. |
Empty issue list | Default 90-day window excludes older issues | Add search text or project filter; issues outside the window need explicit JQL via search. |
Editing is disabled on description | Unsupported ADF (images, tables, …) | Edit in JIRA, or remove unsupported blocks. |
Cannot save workspace scope | Not an administrator | Use individual scope, or ask an admin. |
Link button does nothing | Document not saved / missing context | Save document to a folder first. |
Issue visible in JIRA but not in Brainframe | API user lacks project permission | Grant Browse/View issues to the token’s Atlassian user. |
Related integrations
Task workflows follow the same Add from integrations / Task from integrations pattern for Asana, Monday.com, Azure DevOps and SolarWinds Service Desk — only the browse screen and credential setup differ.
For Confluence pages, Microsoft Entra ID directory objects, Aikido security findings and other categories, use the same integrations browser without the Tasks filter.
Updated on: 14/07/2026
Thank you!