TOPdesk integration with Entra ID and HR: joiners to leavers

If you maintain person cards in TOPdesk by hand, you fall a little further behind with every joiner, internal move and leaver. You only notice when something goes wrong: a new employee cannot log a call on their first day, or a request sits with a manager who has already left.

TOPdesk can take person data from Microsoft Entra ID and from an HR system. Once that import is right, you can align joiners, movers and leavers with it.

Choose one leading source per field

Entra ID holds accounts, group memberships and often the manager. The HR system knows the start and leaving dates, the job title and the formal department. Some fields, such as the department, exist in both.

So decide per field which source leads, for example HR for the department, and let TOPdesk fill that field from that source only. A field fed from two sources will sooner or later hold conflicting values. And whatever the import fills, you no longer edit by hand.

The routes TOPdesk offers

It all starts with the Supporting Files import, under Settings > Import settings > Supporting Files imports. The import wizard handles persons, operators, person groups and departments, among others. As the source you choose a CSV or Excel file, Entra ID, SCIM, an on-premises Active Directory or an MS SQL database.

Another system, such as your HR system, can also create, update and archive persons through the Supporting Files API.

Entra ID as the source

You register TOPdesk as an application in Entra ID, with the read permissions GroupMember.Read.All and User.Read.All and admin consent. Besides person details, you can import the manager (the Manager field), and group memberships as person groups. Only direct memberships are imported, not those through a nested group.

SCIM

With SCIM, TOPdesk does not fetch the data itself. Entra ID sends it to TOPdesk's SCIM API, including deletions, and an import with SCIM as its source turns it into person or operator cards. According to TOPdesk, Entra ID synchronises changes roughly every 40 minutes. Connect one SCIM client per environment, as multiple clients can overwrite each other's data.

A file from the HR system

Without a direct connection to the HR system, use a CSV or Excel export. A script uploads the file with an API account, and the import runs every time a file with the configured name arrives. The task scheduler for that script is not part of TOPdesk; you arrange it yourself.

Joiners

For new employees, enable card creation in the import settings. As the unique key, choose a field that is unique in both the source and TOPdesk, such as the employee number.

Then the login name. Single Sign-on via SAML with Entra ID only works if the person exists in TOPdesk and the login name on the card matches an attribute in Entra ID; TOPdesk recommends the userPrincipalName. So include the login name in the field mapping, along with the field that grants access to the TOPdesk SelfServicePortal. Otherwise a new colleague cannot get in on their first day.

For what a new employee needs, TOPdesk gives its own example: a form in the SelfServicePortal registers a (Preliminary) Request for Change and applies a change template, which creates the activities for the teams involved. In an Extensive Change, activities can depend on each other, so a workstation is only set up once it has been ordered and delivered. Setting up such templates is covered in Change management in TOPdesk.

To start the request as soon as HR records a new employee, use Action Management. With a webhook, an external system starts an action sequence, which can create a change based on a template through the API. The HR system must then be able to send an HTTP request with the credentials of an operator allowed to trigger webhooks.

Movers

With an internal move, the department, manager and group memberships change. If the import may update existing cards, TOPdesk picks up those changes the next time the import runs.

With person groups you make services and their forms available in the SelfServicePortal. If the groups come from Entra ID, a colleague sees the new department's offering after the move. The import can create missing person groups itself.

If someone becomes an operator and you create the operator card through the import, TOPdesk requires it to be linked to a person card.

Leavers

In the import settings you choose what happens to cards no longer in the source: ignore or archive them. Archiving a person card also archives a linked operator card.

The import follows the source, even when it is wrong. A too-narrow filter or an incomplete file can archive many cards in one go. So check the Preview step in the wizard before you save; it shows how many cards will be created, updated and archived. Also set up a failure notification, so TOPdesk emails you when an import fails.

And allow the import to unarchive cards. Anyone who returns then gets their old card back, and a card archived by mistake becomes active again with the next complete import. There is a limit to that: TOPdesk automatically anonymises archived persons after a period you set yourself. According to the documentation, this is on by default and cannot be undone. Align the period with your retention policy, and make sure a mistake is noticed well before then.

For tasks such as collecting equipment, use a template with activities, as for joiners. For keeping the asset register current, see our article on asset management in TOPdesk.

Which route fits

The choice depends mainly on where the reliable data lives, and that can differ per field. We build integrations between TOPdesk and HR systems or Entra ID, from a one-off import to continuous synchronisation, and also set up Change Management and the SelfServicePortal. You can read more on the TOPdesk consultancy page.