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.

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

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

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:

Type	Velden
Incident	Vestiging (verplicht), plus optioneel Categorie, Subcategorie, Behandelaarsgroep, Behandelaar en Vervaldatum
Wijziging	Wijzigingssjabloon en Aanvrager, beide verplicht

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.

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.