> ## 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 Assets integration

# 📦 **JIRA Assets Integration**

> **"Bring your Atlassian CMDB into Brainframe — browse Assets schemas and object types, then import live CMDB records into your GRC folders."**
> *Connect Atlassian Assets with OAuth, choose which schemas and object types matter for compliance, and keep imported assets, documents and identities current without copy-pasting from Jira.*

The **JIRA Assets** integration connects Brainframe to **Atlassian Assets** (Insight / CMDB) on **Jira Cloud**. Unlike the **JIRA** issues integration (API token + issue tracking), Assets uses **OAuth 2.0 (3LO)** with a **user context**, because Atlassian Assets rejects app-only and service-account tokens for these APIs.

Once configured, you can:

* Browse **schemas** and **object types** you explicitly include
* Search objects with **Assets Query Language (AQL)** filters built from the UI
* **Import** objects as Brainframe documents (single or bulk)
* Open imported documents and see **live data** refreshed from Assets

In the integrations catalog, JIRA Assets is classified under **Assets** and **Documents** (alongside inventory-style connectors such as Microsoft Defender devices or Intune). It is **not** a **Tasks** integration — you do **not** use the document bolt (⚡) **Task from integrations** menu for Assets. Use **Add from integrations** from folders and table views instead.

> 💡 The classic **JIRA** integration (issues / tasks) is separate. You can run both on the same Atlassian site. Assets needs its own OAuth app, scopes, and configuration.

---

## 1️⃣ Before You Begin

To configure the integration you will need:

* 🛠 A **Brainframe workspace administrator** (configuration is admin-only).
* 🔐 An **Atlassian Cloud** site where **Assets** is available (typically via a **Jira Service Collection** / Assets licence).
* 🪪 Access to the [Atlassian developer console](https://developer.atlassian.com/console/myapps/) to create an **OAuth 2.0 (3LO)** app.
* 👤 An Atlassian user who can **consent** to the app and who has permission to **read** the Assets schemas and objects you want to browse.
* 📂 Brainframe **document types** ready for import (e.g. Workstation, Application, Supplier) — you map each included object type to a default document type during setup.

> || ⚠️ Brainframe targets **Atlassian Cloud Assets**. Self-hosted Jira Server / Data Center Assets is not supported by this connector.

> || ⚠️ Assets must be **provisioned and licensed** on the site. If the workspace ID cannot be resolved after OAuth, Brainframe shows that Assets is not available on that site.

---

## 2️⃣ Configure the Integration

Go to **Workspace Settings → Integrations → JIRA Assets → Configure** (`/integrations/jira-assets/config`).

If you open **JIRA Assets** before credentials and connection are ready, Brainframe redirects you to this configuration page automatically.

Configuration is a **five-step** wizard. Later steps appear only after earlier ones succeed.

### Step 1 — Atlassian OAuth app

Create a **user-context** OAuth 2.0 (3LO) app, then paste the Client ID and Client secret into Brainframe.

1. Open the [Atlassian developer console](https://developer.atlassian.com/console/myapps/) and create an **OAuth 2.0 (3LO)** app.
2. Under **Authorization**, set the **Callback URL / Redirect URL** exactly to the value shown in Brainframe (copyable field). It has the form:

   `https://<your-brainframe-host>/integrations/jira-assets/callback`

3. Under **Permissions**, add/configure **Jira API**, then:

| Scope area | Scopes to enable |
| ---- |
| **Classic** → *Jira Service Management API* | `read:servicedesk-request` |
| **Granular** | `read:cmdb-object:jira`, `read:cmdb-schema:jira`, `read:cmdb-type:jira`, `read:cmdb-attribute:jira`, `read:cmdb-config:jira` |

4. Add/configure **User identity API** with:

| Scope |
| ---- |
| `read:me` |

5. Under **Settings**, copy the **Client ID** and **Client secret**.
6. In Brainframe, paste them and click **Save OAuth app**.

| Field | Description |
| ---- |
| **Client ID** | From the Atlassian app settings. Required on every save (the full ID is never returned to the browser after storage). |
| **Client secret** | Write-only. Encrypted at rest; leave blank when updating only the Client ID if a secret is already stored. |

> 📌 Client secrets and access tokens **never** leave the Brainframe backend after save. The browser only receives masked metadata (connected site, account email, workspace id, missing-scope hints).

### Step 2 — Connect to Atlassian (OAuth 3LO)

Click **Enable connection** (or **Reconnect** later). You are redirected to Atlassian to grant the requested scopes, then returned to Brainframe’s callback page.

After consent:

* Brainframe stores the user-context tokens.
* It discovers the **Assets workspace** for the selected site.
* If your Atlassian account can access **multiple sites**, you are asked to **Select Atlassian site**.
* The config screen then shows **Site**, **Account**, and **Assets workspace** id when resolved.

| Status | Meaning |
| ---- |
| **Connected** + workspace id shown | Ready to select schemas. |
| **Connected** but workspace **Not resolved** | Assets is not licensed/provisioned on that site — enable Assets, then reconnect. |
| **Missing Atlassian scopes** | Add the listed scopes on the Atlassian app, then reconnect. |

Use **Disconnect** to clear the OAuth session from Brainframe when rotating apps or changing sites.

> || ⚠️ Assets **requires a user-context connection**. App-only / service-account tokens are rejected — Brainframe will report this clearly if the capability check detects it.

### Step 3 — Select schemas

Once connected with a resolved Assets workspace, Brainframe lists available **object schemas**.

* Tick each schema you want to expose as a **tab** in the browser.
* Only selected schemas are stored in the workspace configuration.

### Step 4 — Configure object types

For each selected schema, Brainframe loads **object types**. For every type you care about:

| Setting | Purpose |
| ---- |
| **Include** | Makes the type browsable and importable. |
| **GRC theme** | Organisational tag: **Assets**, **Documents**, or **Identities** (how you think about that CMDB class in GRC). |
| **Default document type** | Brainframe FactType used when importing objects of this type (required when included). Hardware-like names (server, laptop, workstation, device, …) may suggest **Workstation** automatically. |
| **Properties to show in table** | Up to **4** custom Assets attributes as extra browser columns (in addition to the standard Name / Key / Type / Status / Updated fallback when none are chosen). |

Click **Save configuration** when the mapping is ready.

> 📌 Include only the object types your compliance or asset programmes need. Large schemas stay usable when you limit types and columns.

### Step 5 — Test & activate

The integration becomes **active** when all of the following are true:

1. Atlassian is connected over OAuth 3LO  
2. The Assets workspace ID resolves  
3. At least one schema with at least one **included** object type is saved  

Use **Test connection** to run a capability probe. Typical outcomes:

| Result | What it means | What to do |
| ---- |
| **Available** | Token, scopes and workspace OK; schemas listed | Open Jira Assets |
| **Scope not authorized** | Missing exact scopes | Add scopes on the Atlassian app → reconnect |
| **Assets isn’t available on this site** | No workspace / no Assets licence | Enable Assets / Service Collection on the site |
| **User-context connection required** | App-only token detected | Reconnect via OAuth 3LO consent |
| **Reconnect required** | Session expired | Reconnect |
| **Not connected yet** | OAuth app or consent incomplete | Finish Steps 1–2 |

When active, click **Open Jira Assets** to browse.

---

## 3️⃣ Using the JIRA Assets Integration Page

Open **Workspace Settings → Integrations → JIRA Assets** (or the **Integrations** sidebar item when enabled).

Header actions:

| Control | Behaviour |
| ---- |
| **Refresh** | Reloads Assets queries and dashboard KPIs |
| **Configure** | Returns to the setup wizard (admins) |
| **Show documentation** | Opens this help article |

### 📊 KPI cards

| Card | Content |
| ---- |
| **Total in scope** | Count of objects matching your included schemas/types |
| **Recently updated (Nd)** | Objects updated in the recent window (default **7** days) |
| **Objects by schema** | Per-schema counts as badges (when multiple schemas contribute) |

### 🗂 Schema tabs and filters

* Each **selected schema** becomes a tab (hidden when only one schema is configured).
* **Object type** filter: *All types* or one included type.
* **Search**: matches object **Name** with AQL `Name LIKE "…"`.
* **Open Jira Assets dashboard**: opens the site’s Assets UI in a new tab.

### 📋 Object table

| Feature | Behaviour |
| ---- |
| **Columns** | Configured attribute columns for the active type(s); otherwise Name, Key, Type, Status, Updated |
| **Status badges** | Status-type attributes rendered as badges |
| **Checkboxes** | Multi-select for bulk import |
| **Import** | Per-row import into a Brainframe folder |
| **Pagination** | Previous / Next with configurable rows per page |

---

## 4️⃣ Importing Assets Objects into Brainframe

Import creates a **native Brainframe document** linked to the Assets object.

| Action | How |
| ---- |
| **Import one** | Click **Import** on a row |
| **Bulk import** | Select rows → **Import selected** |
| **Folder & type** | Folder picker opens; default document type comes from the object-type mapping (or the current table’s type when started from a table view) |

On import, Brainframe stores:

* Title from the object label (and key when distinct)
* An HTML snapshot of key attributes (fallback if a later live fetch fails)
* An integration URL pointing at the live Assets viewer inside Brainframe
* Source metadata (object type, schema, workspace, Assets URL, payload)

### Live data on imported documents

When you open an imported document, Brainframe fetches the **latest** object from Assets and shows:

* Label, object key, type, schema, status  
* Created / updated timestamps  
* Attribute grid (including referenced objects and multi-values)  
* **Open in Jira Assets** when an external Assets URL is available  

If the live fetch fails, Brainframe falls back to the stored HTML snapshot from import time.

> 📌 Brainframe **reads** Assets data for browse and import. It does not create or modify Assets objects in Atlassian from this integration.

---

## 5️⃣ Add from Integrations — Folders and Table Views

You do not need the full integration page for every import.

### Folder **NEW** menu

1. Open a folder → **NEW** → **Add from integrations**.
2. Select **JIRA Assets** (filter catalog by **Assets** or **Documents** if helpful).
3. Browse the same schema tabs, filters and table as the main page.
4. Import one or many objects into the folder.

### Table view — cloud button

In a document-type table, click the **cloud** icon (**Add from integrations**). The Assets browser opens with the **current table’s document type** pre-selected for import — useful when filling an asset register table.

> 📌 JIRA Assets does **not** appear under **Task from integrations** (bolt menu). That menu is reserved for task providers (JIRA issues, Asana, Monday.com, Azure DevOps, etc.).

---

## 6️⃣ Sidebar Integrations Menu

When JIRA Assets is **configured and enabled** in your workspace menu settings, it appears under **Integrations** in the left sidebar.

* Opens `/integrations/jira-assets` when the integration is active.
* Greyed-out entries mean the item is visible in menu configuration but **not enabled** or **not accessible** for your user — ask an administrator under **Workspace Settings → Menu interface**.

Configuration remains at **Integrations → JIRA Assets → Configure** (workspace administrators).

---

## 7️⃣ How CISOs and Compliance Teams Typically Use Assets in Brainframe

| GRC artefact | Assets source | Why it helps |
| ---- |
| **Asset / CMDB register** | Hardware, applications, services object types | Authoritative inventory linked to risks and controls |
| **Supplier / third-party register** | Vendor or contract object types (Documents theme) | Keep supplier evidence tied to live CMDB attributes |
| **Identity-related inventory** | People / account object types (Identities theme) | Bridge CMDB ownership fields into access reviews |
| **Control evidence** | Critical systems tagged in Assets | Demonstrate scope and ownership for audits |
| **Risk context** | Imported servers / apps linked to risks | Enrich risk descriptions with live status and owners |

### Example programmes

* **ISO 27001 asset inventory (A.5 / A.8)** — Include workstation/server types → import into a governed asset folder → link to risk treatments.
* **NIS2 / critical services** — Map service and dependency object types → import into an “essential entities” register.
* **Vendor risk** — Map supplier object types with Documents theme → import next to questionnaire / contract records.
* **Audit sampling** — Filter recently updated objects → bulk-import a sample set with live refresh for walkthroughs.

### Pair with other Atlassian integrations

| Integration | Role alongside Assets |
| ---- |
| **JIRA** (issues) | Remediation tickets and CAPA as **tasks** linked to imported assets |
| **Confluence** | Policies and runbooks as **documents** related to the same systems |

---

## 8️⃣ Permissions Summary

| Action | Who |
| ---- |
| Save OAuth app / connect / configure schemas & types | **Workspace administrator** |
| Browse and import Assets objects | Users with access to the enabled integration + write access to the target folder |
| Integrations sidebar item | Integration enabled in menu config + active connection + user/group access |
| Consent to Atlassian OAuth | Atlassian user used for the 3LO flow (tokens act with that user’s Assets permissions) |

> 📌 All Assets API calls are proxied through the Brainframe backend. Client secrets and tokens are never returned to the browser after save.

---

## 9️⃣ Troubleshooting

| Symptom | Likely cause | What to do |
| ---- |
| Redirected to **Configure JIRA Assets** | Not connected / not active | Complete Steps 1–5; include at least one object type |
| **Assets isn’t available on this site** | No Assets licence or workspace | Enable Assets / Service Collection; reconnect |
| **Scope not authorized** / missing scopes listed | Atlassian app scopes incomplete | Add the exact scopes from Step 1; reconnect |
| **User-context connection required** | App-only token | Use **Enable connection** (3LO), not a client-credentials-only approach |
| **Failed to load object types** (scope error) | Token missing CMDB scopes | Reconnect after fixing scopes |
| Empty browser / “No schemas or object types” | Nothing included in config | Select schemas and **Include** object types; save |
| Search returns nothing | Name does not start with the search text | AQL `LIKE` is starts-with on **Name** — try a shorter prefix |
| Live viewer shows snapshot only | Temporary API / permission error | Check connection; **Open in Jira Assets**; confirm the Atlassian user can still read the object |
| Cannot open **Configure** | Not an administrator | Ask a workspace admin |
| Multiple Atlassian sites | Account linked to several clouds | Choose the correct site on the callback **Select Atlassian site** screen |

---

## Related integrations

* **JIRA** — Issue tracking and **Task from integrations** workflows (separate credentials / API token).
* **Confluence** — Knowledge pages as **Documents**.
* **Microsoft Defender / Intune / Entra ID** — Other **Assets** / **Identities** inventory sources using the same **Add from integrations** pattern.

For the shared catalog, credential overview and menu behaviour, see the general **Integrations** article.