TOPdesk

Tidal Control's TOPdesk integration connects to your TOPdesk ITSM instance for compliance purposes. It is a two-way integration:

• TOPdesk → Tidal Control: compliance tests read operator access, incident handling and change management.
• Tidal Control → TOPdesk: from a Tidal task or issue you can raise a TOPdesk incident or change, and Tidal keeps its status in sync. This lets your first line keep working in TOPdesk while your second line keeps oversight in Tidal Control.

Nothing is modified or deleted in TOPdesk. Tidal reads data and, only when you explicitly ask it to, creates a new incident or change.

What this integration monitors

• Operators: Login permission, email, job title, branch, department, and ITSM role flags (first line, second line, change coordinator, installer, problem manager)
• Operator groups: Group membership per operator
• Permission groups: Which permission groups exist in your instance
• Incidents: Status, category, urgency, priority, response and completion dates, and major-call flag
• Change requests: Change type, status, phase, requester, category, impact, priority, and closing date

Requirements

• Super User role in Tidal Control
• A TOPdesk operator account with API access and permission to create application passwords
• The Change Management module (optional), needed for the change management checks and for raising TOPdesk changes from Tidal

Configuration step-by-step plan

We'll set up the required permissions on a TOPdesk operator account, create an application password for that account, then add the connection in Tidal Control.

Configuration steps:

1. Set the required permissions on the operator account
2. Create an application password in TOPdesk
3. Configure the integration in Tidal Control

Step 1: Set the required permissions on the operator account

Use a dedicated operator account for the integration rather than a personal one. Permissions in TOPdesk are assigned per permission group, so set them on the permission group the account belongs to.

Permission	Access	Needed for
API access → REST API	Read	All API calls
API access → Use application passwords	Write	Authenticating with an application password
Supporting Files → Operators	Read	Operators, and the operator list in the external-issue dialog
Supporting Files → Operator Groups	Read	Operator groups, and the Operator group field
Supporting Files → Branches	Read	The Site field when raising an incident
Supporting Files → Persons	Read	The Requester field when raising a change
Supporting Files → Permission Groups	Read	Permission groups
Call Management → First line calls	Create	Raising a TOPdesk incident from Tidal (optional)
Call Management → Second line calls	Create	Raising a TOPdesk incident from Tidal (optional)

Step 2: Create an application password in TOPdesk

An application password is a separate token for API access. Use it instead of the operator's login password.

• Log in to your TOPdesk instance as the operator account from step 1
• Click your avatar in the top-right corner and choose My settings
• Scroll to Application passwords and click Add
• Enter a name (e.g. Tidal Control) and optionally an expiry date
• Click Save
• Copy the generated password: it is only shown once

Step 3: Configure the integration in Tidal Control

• Go to Settings → Integrations in Tidal Control
• Click the plus icon next to TOPdesk
• Fill in the configuration:
  • Name: A descriptive name, e.g. TOPdesk
  • API URL: Your TOPdesk instance URL, e.g. https://yourcompany.topdesk.net
  • Login name: The login name of the operator account from step 1
  • Application password: The password from step 2
• Click "Create" to save the integration

Configuration fields explained

The integration dialog asks for the following values:

Name:

• A descriptive name for this connection
• For example: TOPdesk, TOPdesk Production

API URL:

• The base URL of your TOPdesk instance, including https://
• For SaaS instances this is https://yourcompany.topdesk.net
• For self-hosted instances, use the URL you normally log in to
• Do not add a path such as /tas/api. Tidal Control appends that itself

Login name:

• The login name of the operator account, not its email address
• This must be the same account the application password was created for

Application password:

• The token generated in step 2, not the operator's login password
• Keep this value secure

Available checks

The integration runs the following checks, grouped by the area they cover:

Access control (ISO 27001 A.9.2, A.9.4):

• Which operators have login access to the service desk
• Which ITSM roles each operator holds, for least-privilege and segregation-of-duties reviews
• Operator group and permission group membership as evidence for access reviews

Incident management (ISO 27001 A.16.1):

• Open and resolved security incidents with their category and priority
• Response and completion dates as SLA evidence
• Major incidents flagged for follow-up

Change management (ISO 27001 A.12.1.2):

• Change requests with their type, status, and phase as RFC lifecycle evidence
• Requester and handling operator for the change audit trail

Raising TOPdesk incidents and changes (Tidal Control → TOPdesk)

From any Tidal task or issue you can raise a TOPdesk ticket, so the person doing the work stays in the tool they already use while the Tidal task keeps the compliance record.

Click the Add external issue icon on a task or issue, choose your TOPdesk connection, then pick a Type. TOPdesk is the only issue tracker with two kinds of ticket, and the fields differ per kind:

Type	Fields
Incident	Site (required), plus optional Category, Subcategory, Operator group, Operator and Due date
Change	Change template and Requester, both required

Tidal fills the title and description from the Tidal item, and records itself as the caller on the incident. Once the ticket exists, its status is synced back to Tidal on the same schedule as the compliance tests, and appears in the External issue column of the Tasks overview.

Verification

The integration is working when all of the following are true:

• Settings → Integrations shows TOPdesk under Configured Integrations
• TOPdesk tests are available in the Tests section
• Test refresh delivers results without authentication errors
• If you granted the create permissions, the Add external issue icon offers TOPdesk on tasks and issues

Frequently asked questions

Does Tidal Control make changes in TOPdesk? It never modifies or deletes anything. It reads operator, incident and change data, and it creates a new incident or change when you explicitly raise one from a Tidal task or issue. If you do not grant the Call Management create permissions, it cannot write at all.

Can I use the operator's normal login password? No. Use an application password. TOPdesk's REST API requires one, and it can be revoked without changing the operator's password.

Does this work with a self-hosted TOPdesk instance? Yes. Enter the URL you normally log in to as the API URL. The account and permission requirements are the same.

Do I need the Change Management module? Only for the change management checks. Everything else works without it.

Common problems

Authentication fails with a 401 error

• Check that the Login name is the operator's login name, not its email address
• Confirm the application password was copied in full and belongs to that same operator account
• The password may have expired or been revoked. Create a new one and update the integration

Tests fail with a 403 error

• The operator's permission group is missing one of the permissions from step 1
• Check API access → REST API (Read) and API access → Use application passwords (Write) in particular

TOPdesk is missing from the "Add external issue" dialog

• The operator account has no create rights. Add Call Management → First line calls (Create), or Second line calls, on its permission group

Raising an incident fails on the Site field

• Site is required for an incident, and its list comes from Supporting Files → Branches (Read). Add that permission if the list is empty

Raising a change fails or offers no template

• Creating a change needs the Change Management module and create rights on it, and both Change template and Requester must be set

Change management checks return no results

• The Change Management module is probably not licensed or enabled on your instance
• Confirm you can open the Changes module in TOPdesk yourself with the same account

No operators or permission groups are returned

• Add Supporting Files → Operators (Read) and Supporting Files → Permission Groups (Read) to the operator's permission group

Still can't figure it out?

Send an email to support@tidalcontrol.com, and we'll get back to you as soon as possible.