# TOPdesk

> De tweerichtings-TOPdesk-integratie. Compliancetests lezen operatortoegang en incidentbehandeling, en je kunt TOPdesk-incidenten en -wijzigingen aanmaken.

Source: https://tidalcontrol.com/nl/docs/integrations/topdesk

Tidal Control's TOPdesk-integratie maakt verbinding met je TOPdesk ITSM-omgeving voor compliancedoeleinden. Het is een **tweerichtingsintegratie**:

- **TOPdesk → Tidal Control**: compliancetests lezen operatortoegang, incidentbehandeling en change management uit.
- **Tidal Control → TOPdesk**: vanaf een taak of issue in Tidal kun je een TOPdesk-**incident** of **wijziging** aanmaken, waarvan Tidal de status synchroon houdt. Zo blijft je eerste lijn in TOPdesk werken terwijl je tweede lijn het overzicht houdt in Tidal Control.

Er wordt niets gewijzigd of verwijderd in TOPdesk. Tidal leest data en maakt alleen een nieuw incident of een nieuwe wijziging aan wanneer je daar expliciet om vraagt.

## Wat deze integratie monitort

- **Operators:** Login permission, e-mail, functietitel, branch, afdeling en ITSM-rolvlaggen (eerste lijn, tweede lijn, change coordinator, installer, problem manager)
- **Operatorgroepen:** Groepslidmaatschap per operator
- **Permission groups:** Welke permission groups in je omgeving bestaan
- **Incidenten:** Status, categorie, urgentie, prioriteit, reactie- en afhandeldatums en de major call-vlag
- **Changes:** Change type, status, fase, aanvrager, categorie, impact, prioriteit en afsluitdatum

## Vereisten

- Super User rol in Tidal Control
- Een TOPdesk operator-account met API-toegang en rechten om application passwords aan te maken
- De module **Change Management** (optioneel), alleen nodig voor de change management checks

## Configuratie stappenplan

We stellen de benodigde rechten in op een TOPdesk operator-account, maken een **application password** aan voor dat account en voegen daarna de verbinding toe in Tidal Control.

**Configuratie stappen:**

1. **Benodigde rechten instellen op het operator-account**
2. **Application password aanmaken in TOPdesk**
3. **Integratie configureren in Tidal Control**

## Stap 1: Benodigde rechten instellen op het operator-account

Gebruik een apart operator-account voor de integratie in plaats van een persoonlijk account. Rechten worden in TOPdesk per permission group toegekend, dus stel ze in op de permission group waar het account bij hoort.

<table>
<thead>
<tr><th>Recht</th><th>Toegang</th><th>Nodig voor</th></tr>
</thead>
<tbody>
<tr><td>API access → REST API</td><td>Read</td><td>Alle API-aanroepen</td></tr>
<tr><td>API access → Use application passwords</td><td>Write</td><td>Authenticeren met een application password</td></tr>
<tr><td>Supporting Files → Operators</td><td>Read</td><td>Operators, en de behandelaarslijst in het venster voor externe issues</td></tr>
<tr><td>Supporting Files → Operator Groups</td><td>Read</td><td>Operatorgroepen, en het veld <strong>Behandelaarsgroep</strong></td></tr>
<tr><td>Supporting Files → Branches</td><td>Read</td><td>Het veld <strong>Vestiging</strong> bij het aanmaken van een incident</td></tr>
<tr><td>Supporting Files → Persons</td><td>Read</td><td>Het veld <strong>Aanvrager</strong> bij het aanmaken van een wijziging</td></tr>
<tr><td>Supporting Files → Permission Groups</td><td>Read</td><td>Permission groups</td></tr>
<tr><td>Call Management → First line calls</td><td>Create</td><td>Een TOPdesk-incident aanmaken vanuit Tidal (optioneel)</td></tr>
<tr><td>Call Management → Second line calls</td><td>Create</td><td>Een TOPdesk-incident aanmaken vanuit Tidal (optioneel)</td></tr>
</tbody>
</table>

> **info:**

**Alleen monitoren?** Wil je uitsluitend de compliancetests (TOPdesk → Tidal), laat dan de create-rechten onder **Call Management** uit. Al het andere in deze lijst is Read, behalve **Use application passwords**, waarvoor TOPdesk Write vereist om te kunnen authenticeren. Incidenten aanmaken vanuit Tidal is dan niet beschikbaar.

**Ook wijzigingen aanmaken?** Voor het aanmaken van een TOPdesk-*wijziging* zijn create-rechten nodig in het rechtenblok **Change Management**, op de wijzigingstypen die je omgeving gebruikt. Het partnerintegratie-sjabloon van TOPdesk zelf dekt alleen incidenten, dus stem de exacte rechten voor wijzigingen af met je TOPdesk-beheerder.

## Stap 2: Application password aanmaken in TOPdesk

Een application password is een apart token voor API-toegang. Gebruik dit in plaats van het loginwachtwoord van de operator.

- Log in op je TOPdesk-omgeving met het operator-account uit stap 1
- Klik op je **avatar** rechtsboven en kies **My settings**
- Scroll naar **Application passwords** en klik op **Add**
- Voer een naam in (bijv. `Tidal Control`) en optioneel een vervaldatum
- Klik op **Save**
- **Kopieer het gegenereerde wachtwoord**: dit wordt slechts één keer getoond

> **warning:**

**Sla het application password direct op.** TOPdesk toont het wachtwoord slechts één keer bij het aanmaken. Als je het venster sluit zonder te kopiëren, moet je een nieuw wachtwoord aanmaken.

## Stap 3: Integratie configureren in Tidal Control

- Ga naar **Instellingen → Integraties** in Tidal Control
- Klik op het **plus-icoon** naast **TOPdesk**
- Vul de configuratie in:
  - **Name:** Een beschrijvende naam, bijv. `TOPdesk`
  - **API URL:** De URL van je TOPdesk-omgeving, bijv. `https://yourcompany.topdesk.net`
  - **Login name:** De login name van het operator-account uit stap 1
  - **Application password:** Het wachtwoord uit stap 2
- Klik op **"Maken"** om de integratie op te slaan

## Configuratievelden uitgelegd

Het integratievenster vraagt om de volgende waarden:

**Name:**
- Een beschrijvende naam voor deze verbinding
- Bijvoorbeeld: `TOPdesk`, `TOPdesk Productie`

**API URL:**
- De basis-URL van je TOPdesk-omgeving, inclusief `https://`
- Voor SaaS-omgevingen is dit `https://yourcompany.topdesk.net`
- Voor self-hosted omgevingen gebruik je de URL waarmee je normaal inlogt
- Voeg geen pad zoals `/tas/api` toe. Tidal Control zet dat er zelf achter

**Login name:**
- De login name van het operator-account, niet het e-mailadres
- Dit moet hetzelfde account zijn waarvoor het application password is aangemaakt

**Application password:**
- Het token uit stap 2, niet het loginwachtwoord van de operator
- Houd deze waarde veilig

## Beschikbare checks

De integratie voert de volgende checks uit, gegroepeerd per gebied:

**Toegangsbeheer (ISO 27001 A.9.2, A.9.4):**
- Welke operators loginrechten hebben op de servicedesk
- Welke ITSM-rollen elke operator heeft, voor least-privilege en functiescheiding
- Lidmaatschap van operatorgroepen en permission groups als bewijs voor access reviews

**Incidentmanagement (ISO 27001 A.16.1):**
- Open en afgehandelde beveiligingsincidenten met categorie en prioriteit
- Reactie- en afhandeldatums als SLA-bewijs
- Major incidents die zijn gemarkeerd voor opvolging

**Change management (ISO 27001 A.12.1.2):**
- Changes met type, status en fase als bewijs van de RFC-levenscyclus
- Aanvrager en behandelend operator voor de change audit trail

## TOPdesk-incidenten en -wijzigingen aanmaken (Tidal Control → TOPdesk)

Vanaf elke taak of issue in Tidal kun je een TOPdesk-ticket aanmaken, zodat degene die het werk doet in zijn eigen tool blijft werken terwijl de taak in Tidal het compliancedossier vasthoudt.

Klik op het icoon **Externe issue toevoegen** op een taak of issue, kies je TOPdesk-verbinding en selecteer een **Type**. TOPdesk is de enige issue tracker met twee soorten tickets, en de velden verschillen per soort:

<table>
<thead>
<tr><th>Type</th><th>Velden</th></tr>
</thead>
<tbody>
<tr><td><strong>Incident</strong></td><td><strong>Vestiging</strong> (verplicht), plus optioneel <strong>Categorie</strong>, <strong>Subcategorie</strong>, <strong>Behandelaarsgroep</strong>, <strong>Behandelaar</strong> en <strong>Vervaldatum</strong></td></tr>
<tr><td><strong>Wijziging</strong></td><td><strong>Wijzigingssjabloon</strong> en <strong>Aanvrager</strong>, beide verplicht</td></tr>
</tbody>
</table>

Tidal vult de titel en omschrijving vanuit het Tidal-item en registreert zichzelf als melder op het incident. Zodra het ticket bestaat, wordt de status volgens hetzelfde schema als de compliancetests terug gesynchroniseerd naar Tidal en verschijnt hij in de kolom **Externe issue** van het takenoverzicht.

> **note:**

**De velden van TOPdesk zijn niet de generieke velden.** Andere issue trackers vragen om een project en een issue type. TOPdesk vraagt om een vestiging, een categorie en een subcategorie voor incidenten, of om een wijzigingssjabloon en een aanvrager voor wijzigingen. Zie [Externe issues](/docs/integrations/external-issues) voor de onderdelen van de werkwijze die overal gelijk zijn: een bestaand ticket koppelen, de statuskolom en het filteren van het overzicht.

## Verificatie

De integratie werkt wanneer het volgende allemaal klopt:

- Instellingen → Integraties toont TOPdesk onder **Geconfigureerde integraties**
- TOPdesk tests zijn beschikbaar in de sectie Tests
- Het verversen van tests levert resultaten op zonder authenticatiefouten

## Veelgestelde vragen

**Brengt Tidal Control wijzigingen aan in TOPdesk?**
Er wordt nooit iets gewijzigd of verwijderd. De integratie leest operator-, incident- en wijzigingsgegevens, en maakt een nieuw incident of een nieuwe wijziging aan wanneer je die expliciet aanmaakt vanuit een taak of issue in Tidal. Zonder de create-rechten onder Call Management kan de integratie helemaal niet schrijven.

**Kan ik het normale loginwachtwoord van de operator gebruiken?**
Nee. Gebruik een application password. De REST API van TOPdesk vereist dit, en het kan worden ingetrokken zonder het wachtwoord van de operator te wijzigen.

**Werkt dit met een self-hosted TOPdesk-omgeving?**
Ja. Vul de URL in waarmee je normaal inlogt als API URL. De eisen aan het account en de rechten zijn hetzelfde.

**Heb ik de module Change Management nodig?**
Alleen voor de change management checks. Al het andere werkt ook zonder deze module.

## Veelvoorkomende problemen

**Authenticatie mislukt met een 401-fout**
- Controleer of bij **Login name** de login name van de operator staat en niet het e-mailadres
- Controleer of het application password volledig is gekopieerd en bij hetzelfde operator-account hoort
- Het wachtwoord kan zijn verlopen of ingetrokken. Maak een nieuw wachtwoord aan en werk de integratie bij

**Tests mislukken met een 403-fout**
- De permission group van de operator mist een van de rechten uit stap 1
- Controleer vooral **API access → REST API (Read)** en **API access → Use application passwords (Write)**

**TOPdesk ontbreekt in het venster "Externe issue toevoegen"**
- Het operator-account heeft geen create-rechten. Voeg **Call Management → First line calls (Create)** toe, of Second line calls, op de permission group

**Een incident aanmaken mislukt op het veld Vestiging**
- **Vestiging** is verplicht bij een incident, en de lijst komt uit **Supporting Files → Branches (Read)**. Voeg dat recht toe als de lijst leeg is

**Een wijziging aanmaken mislukt of er zijn geen sjablonen**
- Voor het aanmaken van een wijziging is de module Change Management nodig met create-rechten, en moeten zowel **Wijzigingssjabloon** als **Aanvrager** gevuld zijn

**Change management checks leveren geen resultaten op**
- De module Change Management is waarschijnlijk niet gelicentieerd of niet ingeschakeld in je omgeving
- Controleer of je met hetzelfde account de module **Changes** in TOPdesk zelf kunt openen

**Er worden geen operators of permission groups teruggegeven**
- Voeg **Supporting Files → Operators (Read)** en **Supporting Files → Permission Groups (Read)** toe aan de permission group van de operator

### Kom je er nog niet uit?

Stuur een e-mail naar support@tidalcontrol.com en we nemen zo snel mogelijk contact met je op.

> **info:**

**Verzamel support-informatie:** Noteer welke browser je gebruikt, de exacte foutmeldingen en welke stappen je al hebt geprobeerd. Dit versnelt de oplossing aanzienlijk.