> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://docs.brainframe.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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](#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](https://id.atlassian.com/manage-profile/security/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

1. Log in to your Atlassian account.
2. Open [Atlassian API tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
3. Click **Create API token**, give it a label (e.g. `Brainframe GRC`), and copy the token immediately.
4. 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. `acme.atlassian.net` (with or without `https://`). Stored exactly as entered. |
| **Email** | 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. `PROJ-42`) — click the row to open in Brainframe. |
| **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 `/integrations/jira/view/{issueKey}`. |
| **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 `factId` is provided on update. |
| **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 |
| **Monday.com** | 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 `brainframeIntegrationUrl` pointing to the live JIRA issue. |
| **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**

1. Open a document (risk, control, audit finding, policy, etc.).
2. Click the **bolt** icon → **Task from integrations**.
3. Select **JIRA** from the catalog (or another task integration).
4. **Search** for an existing issue, or click **New issue** to create one in JIRA.
5. Click **Link** on the issue row.

Brainframe then:

* Creates an **Action** task document with the issue summary as title.
* Sets `brainframeIntegrationUrl` to `/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):

1. Choose **Add from integrations** (cloud icon).
2. The integrations browser opens in **import** mode with the full catalog.
3. Select **JIRA**, search or create issues, then **Import** (or bulk-import with checkboxes).
4. 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.