HR to ITSM
UKG Pro TOPdesk integration: people and onboarding tickets for the Dutch company
With an integration between UKG Pro and TOPdesk, employees of the Dutch company in UKG Pro are persons in TOPdesk, with department, branch and manager, and KoppelHet creates an incident or change for the right operator group for every new colleague, job change or departure. A new employee starts an onboarding incident or a change from your template, and a terminationDate results in an offboarding ticket one week ahead.
What the integration does
Dutch sites using TOPdesk for IT and facilities, while HR for the group runs in UKG Pro, often only hear on the first working day that there is a new colleague. Leavers' access badges are not collected on time.
- HR records a new employee at the Dutch company in UKG Pro.
- Every three hours KoppelHet requests the changed employees and compares with the previous state.
- The person is added in TOPdesk at the branch of their work location, with department and manager, and an onboarding change starts.
- If the department or manager changes, the person in TOPdesk follows.
- One week before the last working day an offboarding ticket arrives for laptop, badge and access; after the last working day KoppelHet archives the person.
- The onboarding incident is in the new colleague's name and goes to the operator group of the branch, with the start date as target date and job, department and manager in the text. If the service desk wants fixed tasks, it becomes a change from a template.
- A new job or department results in a change ticket, so IT adjusts access and equipment.
What to watch for with UKG Pro and TOPdesk
- A terminationDate is fixed in UKG Pro as soon as HR processes the termination. The offboarding ticket arrives one week before that date; a termination with immediate effect gives a ticket in the next run.
- A rehire gets a new lastHireDate in UKG Pro. KoppelHet treats it as a new start and creates an onboarding ticket, even though the person comes out of the TOPdesk archive.
- A US supervisor is named as manager in the onboarding ticket, even if they are only a person without a branch in TOPdesk. IT then knows who decides on hardware and access.
- UKG Pro returns changed employees at most every three hours. For the service desk that is well in time, because a new employee is usually recorded weeks ahead and the onboarding change carries the start date.
- UKG Pro reports which employees changed, not what changed. KoppelHet compares with the previous state, so a new phone number does not produce an unnecessary change in TOPdesk.
- Only employees of the company with country code Netherlands reach this TOPdesk. US colleagues stay out, except a manager of a Dutch employee, who is created as a person without onboarding.
- UKG Pro has four organisation levels that each organisation fills in itself, and TOPdesk a flat list of departments with unique names. At the start we record which level is the department.
- The work location in UKG Pro becomes the branch in TOPdesk. KoppelHet first creates a new location as a branch before people are linked to it.
- For a rehire UKG Pro keeps a last hire date. KoppelHet then restores an archived person from the archive, so earlier tickets stay with the same person.
This integration is also part of joiner, mover, leaver.
How we build and run it
- The integration runs on the KoppelHet platform, hosted in a data centre in the EU.
- Every sync and every error is visible in the functional log; on an error your administrator is notified.
- A change that cannot go through is not half-applied but queued for another attempt.
- KoppelHet is ISO 27001 certified. Data travels encrypted and stays on the platform no longer than needed.
- After go-live we manage the integration and adjust it when your process changes.
- The integration fits next to your existing integration layer. Only the fields in the design are transferred; the platform keeps no register of its own.
Implementation and price
This is not an app you switch on. We build the integration for your organisation on our platform, with building blocks we reuse on every project. So it is custom work that does not start from scratch.
A consultant prepares the intake and analyses both systems. We then record the mapping and exceptions field by field, test in the test or acceptance environment and go live at a moment you choose. Costs are a one-off amount for the setup and a monthly amount for platform, monitoring and support.
Frequently asked questions
Can we also have tickets created for onboarding and offboarding?
Yes. By default an onboarding incident or a change from your template arrives four weeks before the hireDate, and an offboarding ticket one week before the terminationDate.
Is every three hours fast enough for the service desk?
Yes. New employees are usually in UKG Pro weeks in advance, and the onboarding change carries the start date.
Who decides what is in the onboarding change?
Your service desk, through a template in TOPdesk. KoppelHet fills it with the person, the branch and the start date.
What do we need to arrange in UKG Pro?
A service account with read rights on the agreed APIs and the API key of your environment. Your UKG administrator arranges this once.
What about the GDPR?
You are the controller and KoppelHet is the processor, under a data processing agreement. Only data the service desk needs goes to TOPdesk, and every action is in the audit logging.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- UKG Pro is read through the Personnel API with a service account, the US-Customer-Api-Key and basic authentication. employee-changes (at least three hours between calls; employeeNumber, companyId, supervisorId, jobCode, workLocation, orgLevel1Code to orgLevel4Code, emailAddress, hireDate, terminationDate) and employment-details for lastHireDate.
- TOPdesk is written through the TOPdesk REST API (Supporting Files for people, departments and branches, including archiving and restoring; Change for changes from a template). employeeNumber up to 20 characters, firstName up to 30, prefixes up to 10, surName up to 50.
- Tickets through the TOPdesk REST API: incidents with POST /tas/api/incidents (callerLookup to the person, briefDescription, request, category, operatorGroup, targetDate and externalNumber), or changes with POST /tas/api/operatorChanges from a template (template and requester). KoppelHet stores per employee which incident or change has already been created, per hire and per end date.
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in UKG Pro | Field in TOPdesk | Notes |
|---|---|---|
employeeNumber | employeeNumber | At most 20 characters |
firstName | firstName | At most 30 characters |
lastName | surName en prefixes | Split the prefix, at most 10 characters |
emailAddress | email | |
orgLevel-code die de afdeling is | department | |
workLocation | branch | Through a lookup table |
jobCode (omschrijving) | jobTitle | |
supervisorId | manager | |
hireDate en terminationDate | Onboarding- en offboardingwijziging | |
Indiensttreding, wijziging of vertrek | Melding (incidents) of wijziging uit sjabloon (operatorChanges) | Chosen per event at the start |
Gesynchroniseerde persoon | callerLookup of requester | The ticket is in the employee's name |
hireDate of terminationDate | targetDate en briefDescription | For example Onboarding 01-11-2026: name |
Functie, afdeling en leidinggevende | request (tekst van de melding) | |
Vestiging of afdeling | operatorGroup en category | Operator group per branch |
Related
Recruitee → UKG Pro
Recruitee to UKG Pro integration: European hires through the Global New Hire service in UKG Pro
Teamtailor → UKG Pro
Teamtailor to UKG Pro integration: European hires as global new hires
UKG Pro → Active Directory
UKG Pro to Active Directory integration: domain accounts for the Dutch branch
UKG Pro → ADP iHCM
UKG Pro to ADP iHCM integration: salary and terminations of the Dutch pay group to ADP