> ## 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**

> **"Bringen Sie Ihre Atlassian-CMDB in Brainframe — durchsuchen Sie Assets-Schemas und Objekttypen und importieren Sie Live-CMDB-Datensätze in Ihre GRC-Ordner."**
> *Verbinden Sie Atlassian Assets per OAuth, wählen Sie die für die Compliance relevanten Schemas und Objekttypen und halten Sie importierte Assets, Dokumente und Identitäten aktuell — ohne Copy-Paste aus Jira.*

Die **JIRA Assets**-Integration verbindet Brainframe mit **Atlassian Assets** (Insight / CMDB) auf **Jira Cloud**. Anders als die **JIRA**-Issues-Integration (API-Token + Issue-Tracking) nutzt Assets **OAuth 2.0 (3LO)** mit einem **Benutzerkontext**, weil Atlassian Assets App-only- und Service-Account-Token für diese APIs ablehnt.

Nach der Konfiguration können Sie:

* **Schemas** und **Objekttypen** durchsuchen, die Sie ausdrücklich einbeziehen
* Objekte mit **Assets Query Language (AQL)**-Filtern aus der Oberfläche suchen
* Objekte als Brainframe-Dokumente **importieren** (einzeln oder in Bulk)
* Importierte Dokumente öffnen und **Live-Daten** aus Assets aktualisiert sehen

Im Integrationskatalog ist JIRA Assets unter **Assets** und **Documents** eingeordnet (neben inventarartigen Connectors wie Microsoft-Defender-Geräten oder Intune). Es ist **keine** **Tasks**-Integration — Sie verwenden für Assets **nicht** das Dokument-Blitzmenü (⚡) **Task from integrations**. Nutzen Sie stattdessen **Add from integrations** aus Ordnern und Tabellenansichten.

> 💡 Die klassische **JIRA**-Integration (Issues / Tasks) ist separat. Beide können auf derselben Atlassian-Site laufen. Assets benötigt eine eigene OAuth-App, eigene Scopes und eine eigene Konfiguration.

---

## 1️⃣ Bevor Sie beginnen

Für die Konfiguration benötigen Sie:

* 🛠 Einen **Brainframe-Workspace-Administrator** (Konfiguration nur für Admins).
* 🔐 Eine **Atlassian-Cloud**-Site, auf der **Assets** verfügbar ist (typischerweise über eine **Jira Service Collection**- / Assets-Lizenz).
* 🪪 Zugang zur [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/), um eine **OAuth 2.0 (3LO)**-App zu erstellen.
* 👤 Einen Atlassian-Benutzer, der der App **zustimmen** kann und die Assets-Schemas und -Objekte **lesen** darf, die Sie durchsuchen wollen.
* 📂 Brainframe-**Dokumenttypen** für den Import (z. B. Workstation, Application, Supplier) — beim Setup mappen Sie jeden einbezogenen Objekttyp auf einen Standard-Dokumenttyp.

> || ⚠️ Brainframe zielt auf **Atlassian Cloud Assets**. Self-hosted Jira Server / Data Center Assets wird von diesem Connector nicht unterstützt.

> || ⚠️ Assets muss auf der Site **bereitgestellt und lizenziert** sein. Kann die Workspace-ID nach OAuth nicht aufgelöst werden, meldet Brainframe, dass Assets auf dieser Site nicht verfügbar ist.

---

## 2️⃣ Integration konfigurieren

Gehen Sie zu **Workspace Settings → Integrations → JIRA Assets → Configure** (`/integrations/jira-assets/config`).

Öffnen Sie **JIRA Assets**, bevor Anmeldedaten und Verbindung bereit sind, leitet Brainframe Sie automatisch zu dieser Konfigurationsseite weiter.

Die Konfiguration ist ein **fünfstufiger** Assistent. Spätere Schritte erscheinen erst nach erfolgreichen vorherigen Schritten.

### Schritt 1 — Atlassian-OAuth-App

Erstellen Sie eine OAuth-2.0-(3LO)-App im **Benutzerkontext** und fügen Sie Client ID und Client Secret in Brainframe ein.

1. Öffnen Sie die [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) und erstellen Sie eine **OAuth 2.0 (3LO)**-App.
2. Unter **Authorization** setzen Sie die **Callback URL / Redirect URL** exakt auf den in Brainframe angezeigten Wert (kopierbares Feld). Format:

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

3. Unter **Permissions** fügen Sie **Jira API** hinzu/konfigurieren Sie sie, dann:

| Scope-Bereich | Zu aktivierende Scopes |
| ---- |
| **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. Fügen Sie **User identity API** hinzu/konfigurieren Sie sie mit:

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

5. Unter **Settings** kopieren Sie **Client ID** und **Client secret**.
6. Fügen Sie sie in Brainframe ein und klicken Sie auf **Save OAuth app**.

| Feld | Beschreibung |
| ---- |
| **Client ID** | Aus den Atlassian-App-Einstellungen. Bei jedem Speichern erforderlich (die vollständige ID wird nach dem Speichern nie an den Browser zurückgegeben). |
| **Client secret** | Nur schreibbar. Verschlüsselt gespeichert; leer lassen, wenn nur die Client ID aktualisiert wird und bereits ein Secret hinterlegt ist. |

> 📌 Client Secrets und Access Tokens **verlassen** nach dem Speichern **nie** das Brainframe-Backend. Der Browser erhält nur maskierte Metadaten (verbundene Site, Konto-E-Mail, Workspace-ID, Hinweise auf fehlende Scopes).

### Schritt 2 — Mit Atlassian verbinden (OAuth 3LO)

Klicken Sie auf **Enable connection** (später **Reconnect**). Sie werden zu Atlassian weitergeleitet, um die angeforderten Scopes zu erteilen, und danach zur Brainframe-Callback-Seite zurückgeführt.

Nach der Zustimmung:

* Brainframe speichert die Token im Benutzerkontext.
* Es ermittelt den **Assets workspace** der ausgewählten Site.
* Hat Ihr Atlassian-Konto Zugriff auf **mehrere Sites**, werden Sie aufgefordert, **Select Atlassian site** zu wählen.
* Anschließend zeigt die Konfiguration **Site**, **Account** und die **Assets-workspace**-ID, sobald sie aufgelöst ist.

| Status | Bedeutung |
| ---- |
| **Connected** + Workspace-ID angezeigt | Bereit zur Schema-Auswahl. |
| **Connected**, aber Workspace **Not resolved** | Assets ist auf dieser Site nicht lizenziert/bereitgestellt — Assets aktivieren, dann erneut verbinden. |
| **Missing Atlassian scopes** | Die gelisteten Scopes in der Atlassian-App ergänzen, dann erneut verbinden. |

Mit **Disconnect** löschen Sie die OAuth-Sitzung in Brainframe, wenn Sie Apps rotieren oder die Site wechseln.

> || ⚠️ Assets **erfordert eine Verbindung im Benutzerkontext**. App-only- / Service-Account-Token werden abgelehnt — Brainframe meldet das klar, wenn der Capability-Check es erkennt.

### Schritt 3 — Schemas auswählen

Nach Verbindung mit aufgelöstem Assets-Workspace listet Brainframe verfügbare **Object Schemas**.

* Haken Sie jedes Schema an, das als **Tab** im Browser erscheinen soll.
* Nur ausgewählte Schemas werden in der Workspace-Konfiguration gespeichert.

### Schritt 4 — Objekttypen konfigurieren

Für jedes ausgewählte Schema lädt Brainframe **Object Types**. Für jeden relevanten Typ:

| Einstellung | Zweck |
| ---- |
| **Include** | Macht den Typ durchsuchbar und importierbar. |
| **GRC theme** | Organisatorisches Tag: **Assets**, **Documents** oder **Identities** (wie Sie diese CMDB-Klasse im GRC einordnen). |
| **Default document type** | Brainframe-FactType beim Import von Objekten dieses Typs (erforderlich, wenn einbezogen). Hardware-ähnliche Namen (server, laptop, workstation, device, …) können automatisch **Workstation** vorschlagen. |
| **Properties to show in table** | Bis zu **4** benutzerdefinierte Assets-Attribute als zusätzliche Browser-Spalten (zusätzlich zum Standard-Fallback Name / Key / Type / Status / Updated, wenn keine gewählt sind). |

Klicken Sie auf **Save configuration**, wenn das Mapping fertig ist.

> 📌 Beziehen Sie nur Objekttypen ein, die Ihre Compliance- oder Asset-Programme brauchen. Große Schemas bleiben nutzbar, wenn Sie Typen und Spalten begrenzen.

### Schritt 5 — Testen & aktivieren

Die Integration wird **aktiv**, wenn alle folgenden Punkte zutreffen:

1. Atlassian ist per OAuth 3LO verbunden  
2. Die Assets-Workspace-ID ist aufgelöst  
3. Mindestens ein Schema mit mindestens einem **einbezogenen** Objekttyp ist gespeichert  

Mit **Test connection** führen Sie einen Capability-Check aus. Typische Ergebnisse:

| Ergebnis | Bedeutung | Was tun |
| ---- |
| **Available** | Token, Scopes und Workspace OK; Schemas gelistet | Open Jira Assets |
| **Scope not authorized** | Exakte Scopes fehlen | Scopes in der Atlassian-App ergänzen → erneut verbinden |
| **Assets isn’t available on this site** | Kein Workspace / keine Assets-Lizenz | Assets / Service Collection auf der Site aktivieren |
| **User-context connection required** | App-only-Token erkannt | Per OAuth-3LO-Zustimmung erneut verbinden |
| **Reconnect required** | Sitzung abgelaufen | Erneut verbinden |
| **Not connected yet** | OAuth-App oder Zustimmung unvollständig | Schritte 1–2 abschließen |

Wenn aktiv, klicken Sie auf **Open Jira Assets**, um zu browsen.

---

## 3️⃣ Die JIRA-Assets-Integrationsseite nutzen

Öffnen Sie **Workspace Settings → Integrations → JIRA Assets** (oder den **Integrations**-Eintrag in der Seitenleiste, wenn aktiviert).

Header-Aktionen:

| Steuerung | Verhalten |
| ---- |
| **Refresh** | Lädt Assets-Abfragen und Dashboard-KPIs neu |
| **Configure** | Zurück zum Einrichtungsassistenten (Admins) |
| **Show documentation** | Öffnet diesen Hilfeartikel |

### 📊 KPI-Karten

| Karte | Inhalt |
| ---- |
| **Total in scope** | Anzahl Objekte passend zu Ihren einbezogenen Schemas/Typen |
| **Recently updated (Nd)** | Objekte im aktuellen Zeitfenster aktualisiert (Standard **7** Tage) |
| **Objects by schema** | Zähler pro Schema als Badges (bei mehreren Schemas) |

### 🗂 Schema-Tabs und Filter

* Jedes **ausgewählte Schema** wird ein Tab (ausgeblendet, wenn nur eines konfiguriert ist).
* **Object type**-Filter: *All types* oder ein einbezogener Typ.
* **Search**: trifft auf Objekt-**Name** mit AQL `Name LIKE "…"` zu.
* **Open Jira Assets dashboard**: öffnet die Assets-Oberfläche der Site in einem neuen Tab.

### 📋 Objekttabelle

| Funktion | Verhalten |
| ---- |
| **Columns** | Konfigurierte Attributspalten für den/die aktiven Typ(en); sonst Name, Key, Type, Status, Updated |
| **Status badges** | Status-Attribute als Badges |
| **Checkboxes** | Mehrfachauswahl für Bulk-Import |
| **Import** | Import pro Zeile in einen Brainframe-Ordner |
| **Pagination** | Previous / Next mit konfigurierbarer Seitengröße |

---

## 4️⃣ Assets-Objekte in Brainframe importieren

Der Import erstellt ein **natives Brainframe-Dokument**, das mit dem Assets-Objekt verknüpft ist.

| Aktion | Wie |
| ---- |
| **Import one** | **Import** in einer Zeile klicken |
| **Bulk import** | Zeilen auswählen → **Import selected** |
| **Folder & type** | Ordnerauswahl öffnet sich; Standard-Dokumenttyp kommt aus dem Objekttyp-Mapping (oder dem Typ der aktuellen Tabellenansicht) |

Beim Import speichert Brainframe:

* Titel aus Objektlabel (und Key, falls abweichend)
* Einen HTML-Snapshot wichtiger Attribute (Fallback, wenn ein späterer Live-Abruf scheitert)
* Eine Integrations-URL zum Live-Assets-Viewer in Brainframe
* Quellmetadaten (Objekttyp, Schema, Workspace, Assets-URL, Payload)

### Live-Daten in importierten Dokumenten

Beim Öffnen eines importierten Dokuments holt Brainframe das **aktuellste** Objekt aus Assets und zeigt:

* Label, Object Key, Typ, Schema, Status  
* Erstellt- / Aktualisiert-Zeitstempel  
* Attributraster (inkl. referenzierter Objekte und Mehrfachwerte)  
* **Open in Jira Assets**, wenn eine externe Assets-URL verfügbar ist  

Scheitert der Live-Abruf, greift Brainframe auf den beim Import gespeicherten HTML-Snapshot zurück.

> 📌 Brainframe **liest** Assets-Daten für Browse und Import. Es erstellt oder ändert über diese Integration keine Assets-Objekte in Atlassian.

---

## 5️⃣ Add from Integrations — Ordner und Tabellenansichten

Sie brauchen nicht für jeden Import die volle Integrationsseite.

### Ordner-Menü **NEW**

1. Ordner öffnen → **NEW** → **Add from integrations**.
2. **JIRA Assets** wählen (Katalog ggf. nach **Assets** oder **Documents** filtern).
3. Dieselben Schema-Tabs, Filter und Tabelle wie auf der Hauptseite nutzen.
4. Ein oder mehrere Objekte in den Ordner importieren.

### Tabellenansicht — Cloud-Schaltfläche

In einer Dokumenttyp-Tabelle auf das **Cloud**-Symbol (**Add from integrations**) klicken. Der Assets-Browser öffnet sich mit dem **Dokumenttyp der aktuellen Tabelle** vorausgewählt — praktisch für Asset-Register-Tabellen.

> 📌 JIRA Assets erscheint **nicht** unter **Task from integrations** (Blitzmenü). Dieses Menü ist für Task-Anbieter (JIRA-Issues, Asana, Monday.com, Azure DevOps usw.) reserviert.

---

## 6️⃣ Integrations-Menü in der Seitenleiste

Wenn JIRA Assets in den Menüeinstellungen des Workspace **konfiguriert und aktiviert** ist, erscheint es unter **Integrations** in der linken Seitenleiste.

* Öffnet `/integrations/jira-assets`, wenn die Integration aktiv ist.
* Ausgegraute Einträge bedeuten: im Menü sichtbar, aber für Ihren Benutzer **nicht aktiviert** oder **nicht zugänglich** — Admin unter **Workspace Settings → Menu interface** fragen.

Die Konfiguration bleibt unter **Integrations → JIRA Assets → Configure** (Workspace-Administratoren).

---

## 7️⃣ Typische Nutzung durch CISOs und Compliance-Teams in Brainframe

| GRC-Artefakt | Assets-Quelle | Nutzen |
| ---- |
| **Asset- / CMDB-Register** | Hardware-, Anwendungs-, Service-Objekttypen | Maßgebliches Inventar verknüpft mit Risiken und Controls |
| **Lieferanten- / Drittparteien-Register** | Vendor- oder Vertragsobjekttypen (Documents-Theme) | Lieferantennachweise an Live-CMDB-Attribute binden |
| **Identitätsbezogenes Inventar** | Personen- / Konto-Objekttypen (Identities-Theme) | CMDB-Ownership-Felder in Access Reviews einbringen |
| **Control-Nachweise** | Kritische Systeme in Assets gekennzeichnet | Scope und Ownership für Audits belegen |
| **Risikokontext** | Importierte Server / Apps mit Risiken verknüpft | Risikobeschreibungen mit Live-Status und Ownern anreichern |

### Beispielprogramme

* **ISO-27001-Asset-Inventar (A.5 / A.8)** — Workstation-/Server-Typen einbeziehen → in einen gesteuerten Asset-Ordner importieren → mit Risikobehandlungen verknüpfen.
* **NIS2 / kritische Dienste** — Service- und Abhängigkeitsobjekttypen mappen → in ein Register „wesentlicher Einrichtungen“ importieren.
* **Lieferantenrisiko** — Lieferantenobjekttypen mit Documents-Theme mappen → neben Fragebögen / Verträgen importieren.
* **Audit-Stichproben** — Kürzlich aktualisierte Objekte filtern → Stichprobe bulk-importieren mit Live-Refresh für Walkthroughs.

### Kombination mit anderen Atlassian-Integrationen

| Integration | Rolle neben Assets |
| ---- |
| **JIRA** (Issues) | Remediation-Tickets und CAPA als **Tasks**, verknüpft mit importierten Assets |
| **Confluence** | Richtlinien und Runbooks als **Documents** zu denselben Systemen |

---

## 8️⃣ Berechtigungsübersicht

| Aktion | Wer |
| ---- |
| OAuth-App speichern / verbinden / Schemas & Typen konfigurieren | **Workspace-Administrator** |
| Assets-Objekte browsen und importieren | Benutzer mit Zugang zur aktivierten Integration + Schreibrecht auf den Zielordner |
| Integrations-Seitenleisteneintrag | Integration in Menükonfiguration aktiviert + aktive Verbindung + Benutzer-/Gruppenzugriff |
| Atlassian-OAuth-Zustimmung | Atlassian-Benutzer des 3LO-Flows (Token wirken mit dessen Assets-Berechtigungen) |

> 📌 Alle Assets-API-Aufrufe laufen über das Brainframe-Backend. Client Secrets und Token werden nach dem Speichern nie an den Browser zurückgegeben.

---

## 9️⃣ Fehlerbehebung

| Symptom | Wahrscheinliche Ursache | Was tun |
| ---- |
| Weiterleitung zu **Configure JIRA Assets** | Nicht verbunden / nicht aktiv | Schritte 1–5 abschließen; mindestens einen Objekttyp einbeziehen |
| **Assets isn’t available on this site** | Keine Assets-Lizenz oder kein Workspace | Assets / Service Collection aktivieren; erneut verbinden |
| **Scope not authorized** / fehlende Scopes gelistet | Atlassian-App-Scopes unvollständig | Exakte Scopes aus Schritt 1 ergänzen; erneut verbinden |
| **User-context connection required** | App-only-Token | **Enable connection** (3LO) nutzen, keinen reinen Client-Credentials-Ansatz |
| **Failed to load object types** (Scope-Fehler) | Token ohne CMDB-Scopes | Nach Scope-Korrektur erneut verbinden |
| Leerer Browser / „No schemas or object types“ | Nichts in der Config einbezogen | Schemas wählen und Objekttypen **Include**; speichern |
| Suche liefert nichts | Name beginnt nicht mit dem Suchtext | AQL `LIKE` ist „beginnt mit“ auf **Name** — kürzeres Präfix versuchen |
| Live-Viewer zeigt nur Snapshot | Temporärer API- / Berechtigungsfehler | Verbindung prüfen; **Open in Jira Assets**; prüfen, ob der Atlassian-Benutzer das Objekt noch lesen kann |
| **Configure** lässt sich nicht öffnen | Kein Administrator | Workspace-Admin fragen |
| Mehrere Atlassian-Sites | Konto mit mehreren Clouds verknüpft | Auf dem Callback-Bildschirm **Select Atlassian site** die richtige Site wählen |

---

## Verwandte Integrationen

* **JIRA** — Issue-Tracking und **Task from integrations**-Workflows (separate Anmeldedaten / API-Token).
* **Confluence** — Wissensseiten als **Documents**.
* **Microsoft Defender / Intune / Entra ID** — Weitere **Assets**- / **Identities**-Inventarquellen mit demselben **Add from integrations**-Muster.

Für gemeinsamen Katalog, Credential-Übersicht und Menüverhalten siehe den allgemeinen Artikel **Integrations**.