> ## 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).

# SolarWinds Integration

# 🎫 **SolarWinds Service Desk Integration**

> **"Connect IT service management to your GRC workflow — browse incidents, problems, changes and CMDB items from Brainframe, and link them to risks, controls and remediation trackers."**
> *Use a SolarWinds Service Desk JSON Web Token to search your tenant through the Samanage REST API, work on records in Brainframe, and tie ITSM work directly to compliance documents.*

The **SolarWinds Service Desk** integration (internally **SWSD**) connects Brainframe to your **SolarWinds Service Desk** tenant via the **Samanage REST API**. Once configured, you can search and manage **incidents**, **problems**, **change requests**, and **CMDB configuration items** from the integrations area — and **link or import** those records as tasks or folder documents, alongside other task integrations such as **JIRA**, **Asana**, **Monday.com**, and **Azure DevOps**.

Brainframe proxies all API traffic through the backend. Your **JSON Web Token is encrypted at rest** and **never returned to the browser** after you save configuration.

---

## 1️⃣ Before You Begin

To configure and use the integration you will need:

* 🛠 A **Brainframe account** with access to the integrations area.
* 👤 A **workspace administrator** to open the credential configuration page and save **workspace** credentials (see [Credential scope](#credential-scope) below).
* 🔐 A **SolarWinds Service Desk** tenant in the correct **region** (EU, US, or APJ — see [Regional URLs](#regional-urls)).
* 🎫 A **JSON Web Token** generated for an admin (or appropriately privileged) user in Service Desk.
* 📂 Sufficient **Service Desk permissions** for that user to list, create, update, and delete the record types you expect to use in Brainframe.

> || ⚠️ Brainframe speaks to the **Samanage REST API** (`X-Samanage-Authorization: Bearer …`). Your **web portal URL** and **API endpoint** must match the same tenant and region, or searches and “Open in Service Desk” links will fail.

> 💡 Unlike Microsoft Entra ID or Microsoft Defender, this integration does **not** provide a KPI dashboard — it focuses on **search, CRUD, import/link**, and **inline document views** of live Service Desk records.

---

## 2️⃣ Configure the Integration

### Step 1 — Generate a JSON Web Token in SolarWinds Service Desk

1. Log in to your **SolarWinds Service Desk** portal (e.g. `https://appeu.samanage.com` for EU).
2. As an administrator, go to **Settings → Users**.
3. Select an **admin user** (or a dedicated integration user with the rights you need).
4. From the user’s **action menu**, **generate a JSON Web Token**.
5. Copy the token immediately — you will paste it once into Brainframe.

> 📌 The token inherits the **permissions of that Service Desk user**. For workspace-wide use, prefer a **service account** with stable access rather than a personal admin token that might be rotated with offboarding.

### Step 2 — Enter credentials in Brainframe

Go to **Workspace Settings → Integrations → SolarWinds Service Desk → Configure** (`/integrations/swsd/config`).

> 📌 The configuration route is restricted to **workspace administrators**. Non-admin users rely on credentials an administrator has already saved (typically **workspace** scope).

Fill in:

| Field | Description |
| ---- |
| **Credential scope** | **Individual** or **Workspace** — see [Credential scope](#credential-scope). |
| **Web interface URL** | Portal URL for your tenant (used for **Open in Service Desk** links). |
| **API endpoint** | REST API base URL for the same tenant and region. |
| **JSON Web Token** | The token from Step 1. Encrypted at rest; never shown again after save. |

Use the **EU**, **US**, or **APJ** shortcut buttons next to **Web interface URL** to pre-fill matching portal and API pairs (you can still edit the URLs manually if your tenant differs).

Then click **Save configuration**. After a successful save, Brainframe opens the Service Desk integration landing page.

> 📌 If no credentials exist for your workspace, opening **SolarWinds Service Desk** redirects you toward configuration. Ensure an administrator has saved **workspace** credentials, or complete setup on the config page as an admin.

### Regional URLs

Brainframe presets align with common SolarWinds Service Desk hosting regions:

| Region | Web interface URL | API endpoint |
| ---- |
| **EU** | `https://appeu.samanage.com` | `https://apieu.samanage.com` |
| **US** | `https://app.samanage.com` | `https://api.samanage.com` |
| **APJ** | `https://appau.samanage.com` | `https://apiau.samanage.com` |

Both URLs must belong to the **same** tenant. If you use a custom domain, enter the exact URLs your SolarWinds documentation provides.

<!-- <IMAGE: SWSD configuration page with scope, regional shortcuts, web URL, API endpoint, and token field> -->

### Credential scope

Brainframe supports two credential models:

| Scope | Who can configure | Who can use |
| ---- |
| **Individual** | Workspace administrator (on the config page) | Only that user when individual credentials exist for them |
| **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 integration user. **Individual** scope suits an admin who connects their own Service Desk identity without sharing a token workspace-wide.

You can **delete** a saved configuration per scope from the config page. Deleting removes stored credentials; you must re-enter the JSON Web Token to reconnect.

---

## 3️⃣ Using the Service Desk Integration Page

Open **Workspace Settings → Integrations → SolarWinds Service Desk** (or the **Integrations** sidebar entry when enabled for your workspace) — `/integrations/swsd`.

<!-- <IMAGE: SWSD data type selector — Incidents, Problems, Changes, CMDB items> -->

### Choose a data type

The landing page lets you pick one of four collections:

| Type | Purpose |
| ---- |
| **Incidents** | Service incidents — triage and status tracking |
| **Problems** | Underlying problems — symptoms, workarounds, root cause |
| **Changes** | Change requests and approval workflow |
| **CMDB items** | Configuration management database assets |

Selecting a type navigates to `/integrations/swsd/{type}` (e.g. `/integrations/swsd/incidents`).

The **gear** icon opens credential configuration (admin). **New** opens the create form for the current type (`/integrations/swsd/{type}/new`).

### 🔎 Search and filters

| Control | Behaviour |
| ---- |
| **Search** | Text search across name, description, and requester context (Samanage `search_in_context`). Press **Enter** or click **Search**. |
| **Status** | Filter by workflow state (incidents, problems, changes — not CMDB). |
| **Priority** | Filter by priority where applicable. |
| **Category** | Filter by category when the type supports categories (e.g. incidents, CMDB). |
| **Item type** | **CMDB only** — filter configuration item type. |
| **Clear** | Resets filters and reloads the first page. |

Results paginate with **Load more** (default **10** records per page). The list shows how many items are loaded versus the total reported by the API.

### 📊 Results list

Each row represents one Service Desk record. Typical columns include title, status, priority, assignee, and dates — exact fields depend on the data type. Actions include:

| Action | Description |
| ---- |
| **Open row** | View detail in Brainframe (`/integrations/swsd/{type}/view/{id}`). |
| **Open in Service Desk** | Opens the record in the SolarWinds portal (new tab) using your saved **web interface URL**. |
| **Select** | Checkbox for **bulk delete** on the integration page. |

### ➕ Create, view, edit and delete

| Action | Where |
| ---- |
| **Create** | **New** on the list page, or **New** inside the integrations browser dialog. |
| **View** | Click a row, or open a linked/imported document whose integration URL points to `/swsd/{type}/view/{id}`. |
| **Edit** | **Edit** on the detail page or inline document view — updates are sent to Service Desk via the API. |
| **Delete** | **Delete** on the detail page, or **bulk delete** from the list when rows are selected. |

When a record is opened **inline on a Brainframe document** and you delete it in Service Desk through Brainframe, the linked Brainframe document can be **archived** automatically.

**Create / edit fields (typical)**

| Field | Notes |
| ---- |
| **Name** | Required title; on update with a linked document, can sync to the Brainframe document title. |
| **Description** | HTML-rich text; images in descriptions may be adjusted for display (`fixSwsdImageUrls`). |
| **Status / priority** | From your tenant’s schemes (filter dropdowns mirror common values; API may return additional labels). |
| **Category / sub-category** | Loaded from Service Desk metadata where supported. |
| **Group, site, department** | Reference data from your tenant (groups, sites, departments APIs). |
| **Assignee** | Selected by user email from Service Desk users. |
| **Problems only** | **Symptoms**, **workaround**, **root cause** fields in addition to description. |
| **CMDB** | **Item type** and CMDB-specific attributes instead of incident-style status workflow. |

Detail view also shows **Created** and **Updated** timestamps, **assignee**, and structured metadata in read mode before you click **Edit**.

<!-- <IMAGE: SWSD incident detail view with status badges and Open in Service Desk> -->

---

## 4️⃣ Task Integrations — Linking Work to Documents

Beyond the standalone Service Desk pages, Brainframe treats SWSD as a **task integration**: you can attach external ITSM records to GRC documents without leaving your compliance context.

Task integrations in Brainframe include:

| Integration | Badge | Typical use |
| ---- |
| **SolarWinds Service Desk** | Tasks / Incidents / Assets | Incidents, changes, problems, CMDB |
| **JIRA** | Tasks | Issue tracking |
| **Asana** | Tasks | Project tasks |
| **Monday.com** | Tasks | Work management |
| **Azure DevOps** | Tasks | Work items |

Service Desk appears under **Tasks**, **Incidents**, and **Assets** filters on the integrations catalog.

### Two modes: **Link** vs **Import**

| Mode | Purpose | Result |
| ---- |
| **Link** | Attach a record **to the document you are working on** | Creates an **Action** (or task) document linked as a child; stores `brainframeIntegrationUrl` as `/swsd/{type}/view/{id}`. |
| **Import** | Add records **into a folder** | Creates document(s) in the folder you choose; supports bulk selection with checkboxes. |

The browser title is **Add from integrations**. When linking from a document, the catalog can be pre-filtered to **Tasks** integrations.

**Workflow in the browser**

1. Choose **SolarWinds Service Desk**.
2. Pick **Incidents**, **Problems**, **Changes**, or **CMDB items**.
3. Search and filter, or click **New** to create a record in Service Desk first.
4. **Link** (document context) or **Import** (folder context) on one or more rows.

---

## 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. |
| **Request document review** | Starts a document review workflow. |
| **Task from integrations** | Opens the integrations browser in **link** mode, filtered to **Tasks**. |

**Workflow — link a Service Desk record to the current document**

1. Open a document (risk, control, audit finding, policy, etc.).
2. Click the **bolt** icon → **Task from integrations**.
3. Select **SolarWinds Service Desk**.
4. Choose the data type, **search** for an existing record, or **New** to create one.
5. Click **Link** on the row.

Brainframe creates a linked task document, sets the integration URL to `/swsd/{type}/view/{id}`, and relates it in the **Tasks / Activities** panel.

> 📌 **Task from integrations** requires a saved document in a folder context. Save the document first if the folder context is not yet available.

Opening a linked task from the document loads the **inline Service Desk viewer** (`IntegrationDocumentView`) — live fields, edit, delete, and **Open in Service Desk** without leaving your GRC record.

<!-- <IMAGE: Inline SWSD record embedded in a document editor> -->

---

## 6️⃣ NEW Menu and Table View — **Add from integrations**

You can bring Service Desk records **into a folder** without linking them to a specific parent document.

### Folder view — **NEW** dropdown

In any folder, open the **NEW** menu:

1. Choose **Add from integrations**.
2. Select **SolarWinds Service Desk** and a data type.
3. Search or create records, then **Import** (or bulk-import with checkboxes).
4. Pick the target folder and document type in the folder selection step.

### Table view — cloud button

In a **table view**, the toolbar **cloud** button (**Add from integrations**) opens the same browser in **import** mode and can pre-select the current table’s document type.

### Inside the Service Desk browse step

| Action | Import mode | Link mode |
| ---- |
| **Search** | Filter by text, status, priority, category (or CMDB item type). | Same |
| **Import** / **Link** | Per-row action; bulk toolbar for multi-select. | **Link** only |
| **Open** | Opens record in Service Desk portal. | Same |
| **New** | Creates in Service Desk, then imports or links based on mode. | Same |
| **Configure** | Shortcut to credential settings (admin). | Same |

---

## 7️⃣ Sidebar Integrations Menu

When **SolarWinds Service Desk** is **configured and enabled** for your user or group, it appears under the workspace **Integrations** sidebar menu (alongside other enabled integrations).

* **SolarWinds Service Desk** opens `/integrations/swsd` — the data type selector and browse flows in section 3.
* Greyed-out entries mean the integration is visible in menu configuration but **not enabled** or **not accessible** for you — ask an administrator to enable it under **Workspace Settings → Menu interface**.

Configuration remains at **Integrations → SolarWinds Service Desk → Configure** (`/integrations/swsd/config`) for workspace administrators.

---

## 8️⃣ Permissions Summary

| Action | Requirement |
| ---- |
| Open **configuration** page | Workspace administrator |
| Save **workspace** credentials | Workspace administrator |
| Save **individual** credentials | Workspace administrator (on config page) |
| Browse / create / edit / delete records | Valid credentials (individual or workspace) + Service Desk rights for the API user |
| **Task from integrations** (link) | Document saved in a folder; permission to create documents and relations |
| **Add from integrations** (import) | Write access to target folder |
| Integrations sidebar menu item | Integration enabled in menu config + user/group access |

> 📌 Brainframe never exposes the JSON Web Token to the browser after save. All Samanage API calls are proxied through the Brainframe backend with `X-Samanage-Authorization`.

---

## 9️⃣ Tips for GRC Use Cases

| Scenario | Suggested approach |
| ---- |
| **IT incident linked to a risk or finding** | Open the risk document → bolt → **Task from integrations** → Service Desk → link or create an **incident**. |
| **Change record for a control deployment** | Browse **Changes**, link to the control document, track approval status inline. |
| **Problem management for recurring audit themes** | Import **problems** into an audit folder; use symptoms/workaround fields for assessor context. |
| **CMDB asset as evidence** | Import **CMDB items** into an asset or evidence folder; badge **Assets** on the integrations catalog. |
| **Bulk cleanup after import test** | Use row selection and **bulk delete** on `/integrations/swsd/{type}` (deletes in Service Desk — use with care). |
| **Shared vs personal connection** | **Workspace** credentials for a shared integration user; **individual** when only one admin’s token should apply for that admin’s session resolution. |

---

## 🔟 Troubleshooting

| Symptom | Likely cause | What to do |
| ---- |
| Redirected away from **Configure** | Not a workspace administrator | Ask an admin to save **workspace** credentials, or grant admin access for setup. |
| Redirect to config when opening SWSD | No credentials for your user/workspace | Admin saves workspace (or individual) credentials on `/integrations/swsd/config`. |
| **Failed to load** search results | Invalid token, wrong API endpoint, or revoked JWT | Regenerate JSON Web Token in Service Desk; verify **EU/US/APJ** API URL matches portal tenant. |
| Empty list | Filters too strict or no matching records | Clear filters; broaden search text; confirm API user can see records in Service Desk UI. |
| **Open in Service Desk** wrong tenant | **Web interface URL** mismatch | Align **website** field with the portal you use to log in (use regional preset buttons). |
| Create/update fails | Missing required Service Desk fields or insufficient role | Check mandatory fields for that type in Service Desk; widen integration user permissions. |
| **Link** does nothing | Document not saved / missing folder context | Save document to a folder first. |
| Record visible in Service Desk but not in Brainframe | API user lacks visibility | Grant the token user the same catalog/search rights as in the portal. |
| Inline view does not load | Integration URL not in `/swsd/{type}/view/{id}` form | Re-link or re-import so the document stores the correct `brainframeIntegrationUrl`. |

---