HR to ITSM
Lucca to TOPdesk integration: persons and branches from Lucca job positions, with tickets for joiners and leavers
With an integration between Lucca and TOPdesk, every employee from Lucca is a person in TOPdesk, with the branch, department and manager from their current job position, and the service desk gets a timely ticket for every joiner and leaver. KoppelHet reads the employments and job positions in Lucca, so even a transfer that takes effect later reaches TOPdesk on the right day.
What the integration does
Organisations that use Lucca for HR, leave and expenses, and TOPdesk as service desk, often receive new colleagues at IT through a form or an email. Because Lucca records a transfer as a new job position, the service desk only notices a move to another office when the employee calls to say their badge does not work.
- HR records an employment in Lucca with a first job position, establishment and manager.
- Lucca sends an event. KoppelHet fetches the employee and their job position and creates the person in TOPdesk.
- Four weeks before the start date an onboarding ticket reaches the operator group of the branch, in the new colleague's name.
- When a new job position starts at another establishment or department, KoppelHet updates the person on the start date and creates a change ticket.
- When the employment gets an end date, an offboarding ticket arrives a week before that day. After the last day KoppelHet archives the person.
What to watch for with Lucca and TOPdesk
- In Lucca the establishment belongs to the job position, not to the employee. A transfer there is a new job position with its own start date. KoppelHet only sets the new branch in TOPdesk on that start date, so tickets keep going to the old location until the last day.
- Lucca calculates an employee's status itself from their employments. Someone who has yet to start has status upcoming. KoppelHet already creates the person in TOPdesk then, so the onboarding ticket can be in the new colleague's name before they arrive.
- An employment in Lucca without an end date is a permanent contract. When an end date is added, that is the last day. KoppelHet uses that date as the target date of the offboarding ticket and as the end date in the person's contract in TOPdesk.
- Lucca lets all integrations of one environment make fifty requests per minute together. A payroll or leave integration counts too. KoppelHet therefore reads only the affected employee after an event and runs the full comparison at night.
- Lucca tries to deliver an event five times, spread over about a day, and keeps events for two months. After an outage KoppelHet fetches missed events afterwards, so a departure does not pass TOPdesk by unnoticed.
- What the integration sees in Lucca depends on the establishments the API access has rights to. If the TOPdesk environment only serves some of the establishments, the integration only gets those, and other countries do not enter TOPdesk.
- Lucca holds one probationary period per employment as a separate record. KoppelHet puts the end of the probation in the onboarding ticket, so the service desk knows when temporary rights should be reviewed.
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
What if someone has two job positions in a row in Lucca?
Lucca always returns the job position that applies today. KoppelHet applies the next position on its start date, with a change ticket if branch or department changes.
Do salary or leave end up in TOPdesk?
No. The integration only reads name, work email, job, establishment, department, manager and dates.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- Lucca is read through the Lucca API (v5, Api-Version header) with OAuth 2.0 and read-only scopes: employees (status upcoming, active or deactivated, calculated from employments), employments (start.date, end.date null for permanent, legalEntity inferred from the first job position, links to probationaryPeriods; filter on lastUpdatedAt, limit up to 1,000) and job-positions (jobTitle, department, businessEstablishment, manager). Events on create, update and delete, via webhook or the events endpoint; five delivery attempts in about 24 hours, kept for two months. Limit of 50 requests per minute per tenant.
- TOPdesk is written through the TOPdesk REST API with an operator's application password: persons and branches through Supporting Files (employeeNumber at most 20 characters, archiving with a reason), incidents with POST /tas/api/incidents (callerLookup, briefDescription, request, operatorGroup, targetDate, externalNumber). KoppelHet stores per employment which ticket already exists.
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in Lucca | Field in TOPdesk | Notes |
|---|---|---|
employee.id | employeeNumber | Or a company employee number if Lucca holds one |
givenName en familyName | firstName en surName | |
email | email | |
applicableJobPosition.jobTitle | jobTitle | |
applicableJobPosition.department | department | |
applicableJobPosition.businessEstablishment | branch | |
applicableJobPosition.manager | manager | |
employment.start.date en end.date | hireDate, employmentTerminationDate en targetDate van de melding | |
Status upcoming, active of deactivated | Persoon actief of gearchiveerd |
Related
Lucca → Active Directory
Lucca to Active Directory integration: accounts in your own domain based on Lucca
Lucca → ADP iHCM
Lucca to ADP iHCM integration: fixed and variable pay from Lucca Compensation to Dutch ADP payroll
Lucca → AFAS Profit
Lucca to AFAS integration: employees and pay of the Dutch entity from Lucca in AFAS
ASLucca → Arbodienst (SIVI)
Lucca to the occupational health service via SIVI: confirmed sickness per half day as absence reports