# TOPdesk

> The two-way TOPdesk integration. Compliance tests read operator access and incident handling, and you can raise TOPdesk incidents and changes from Tidal.

Source: https://tidalcontrol.com/docs/integrations/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.

<table>
<thead>
<tr><th>Permission</th><th>Access</th><th>Needed for</th></tr>
</thead>
<tbody>
<tr><td>API access → REST API</td><td>Read</td><td>All API calls</td></tr>
<tr><td>API access → Use application passwords</td><td>Write</td><td>Authenticating with an application password</td></tr>
<tr><td>Supporting Files → Operators</td><td>Read</td><td>Operators, and the operator list in the external-issue dialog</td></tr>
<tr><td>Supporting Files → Operator Groups</td><td>Read</td><td>Operator groups, and the <strong>Operator group</strong> field</td></tr>
<tr><td>Supporting Files → Branches</td><td>Read</td><td>The <strong>Site</strong> field when raising an incident</td></tr>
<tr><td>Supporting Files → Persons</td><td>Read</td><td>The <strong>Requester</strong> field when raising a change</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>Raising a TOPdesk incident from Tidal (optional)</td></tr>
<tr><td>Call Management → Second line calls</td><td>Create</td><td>Raising a TOPdesk incident from Tidal (optional)</td></tr>
</tbody>
</table>

> **info:**

**Read-only monitoring only?** If you only want the compliance tests (TOPdesk → Tidal), leave the **Call Management** create permissions off. Everything else on this list is Read, apart from **Use application passwords**, which TOPdesk requires as Write in order to authenticate at all. Raising incidents from Tidal will then be unavailable.

**Raising changes as well as incidents?** Creating a TOPdesk *change* needs create rights in the **Change Management** permission block, on the change types your instance uses. TOPdesk's own partner-integration template covers incidents only, so confirm the exact change permissions with your TOPdesk administrator.

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

> **warning:**

**Save the application password immediately.** TOPdesk only shows the password once at creation. If you close the dialog without copying it, you will need to create a new one.

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

<table>
<thead>
<tr><th>Type</th><th>Fields</th></tr>
</thead>
<tbody>
<tr><td><strong>Incident</strong></td><td><strong>Site</strong> (required), plus optional <strong>Category</strong>, <strong>Subcategory</strong>, <strong>Operator group</strong>, <strong>Operator</strong> and <strong>Due date</strong></td></tr>
<tr><td><strong>Change</strong></td><td><strong>Change template</strong> and <strong>Requester</strong>, both required</td></tr>
</tbody>
</table>

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.

> **note:**

**TOPdesk's fields are not the generic ones.** Other issue trackers ask for a project and an issue type. TOPdesk asks for a site, a category and a subcategory for incidents, or a change template and a requester for changes. See [External issues](/docs/integrations/external-issues) for the parts of the workflow that are the same everywhere: linking an existing ticket, the status column, and filtering the 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.

> **info:**

**Gather support info:** Note which browser you're using, exact error messages, and which steps you've already tried. This speeds up the solution considerably.