HR to ITSM
UKG Pro to ServiceNow integration: users with org levels and catalog requests on joining and leaving
With an integration between UKG Pro and ServiceNow, every employee from UKG Pro becomes a user in ServiceNow, with company, department from the org levels, work location and manager, and a hire, rehire or termination in UKG Pro orders the matching item from the ServiceNow service catalog. KoppelHet fetches the changes every three hours, the shortest interval UKG Pro allows.
What the integration does
Organisations that run HR and payroll in UKG Pro and use ServiceNow for IT usually do not see their org structure in ServiceNow. Users arrive through the directory without department or manager, and a rehire is only noticed when someone cannot log in on the first day.
- Every three hours KoppelHet fetches the changed employees from UKG Pro.
- KoppelHet compares each employee with the previous state and keeps only real changes.
- New org levels and work locations go to ServiceNow first, then the users.
- A hire or rehire within the onboarding lead time orders the onboarding item for that user.
- A terminationDate orders the offboarding item; after that date the user is set to inactive.
What to watch for with UKG Pro and ServiceNow
- UKG Pro returns changed employees with at least three hours between two calls, about eight times a day. An immediate termination is therefore in ServiceNow within three hours at most; for hires, which are usually recorded weeks ahead, that interval does not matter.
- On a change UKG Pro delivers the full record, not which fields changed. KoppelHet compares each record with the previous call and only puts employees with a different department, location, job or supervisor in the import set, so ServiceNow does not run thousands of transforms per round.
- UKG Pro has four org levels that the organisation fills in itself. KoppelHet creates them in ServiceNow as departments with a parent department, and loads them level by level, so a new team on level four does not refer to a division that does not exist yet.
- On a rehire the employee gets a new date of last hire in UKG Pro, next to the original one. KoppelHet sees that date, sets the existing user in ServiceNow back to active and orders the onboarding item, so old requests and hardware stay with the same person.
- Every employee has a company in UKG Pro. If the organisation runs several companies in one UKG Pro environment, KoppelHet puts the company on the user in ServiceNow, so assignment and chargeback can be done per company.
- UKG Pro returns a language code per employee. KoppelHet uses it to fill the user's preferred language, so colleagues outside the Netherlands get the service desk portal and notifications in their own language, as far as that language is enabled in ServiceNow.
- The service account in UKG Pro only needs the View role on the EmployeeExport web service. It therefore cannot change anything in UKG Pro, and pay and address fields that are in the same response are dropped by KoppelHet before anything goes to ServiceNow.
- The ServiceNow Store has a UKG app for HR Service Delivery, but it lets employees see balances, schedules and shifts through Virtual Agent. According to the documentation that app does not create users or catalog requests on joining and leaving.
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
Why not more often than every three hours?
UKG Pro does not allow a shorter interval for the change list. For joiners and leavers that is enough, because the onboarding lead time is measured in weeks.
Does pay or address data go to ServiceNow?
No. Those fields are in the UKG Pro response, but KoppelHet only passes on name, work email, company, department, location, job, language, manager and the dates.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- UKG Pro through GET /personnel/v1/employee-changes (startDate, endDate, page, per_Page; at least three hours between calls) with the US-CUSTOMER-API-KEY header and basic authentication of a service account with the View role on EmployeeExport. Fields include employeeId, employeeNumber, companyId, orgLevel1Code to orgLevel4Code, workLocation, supervisorId, jobCode, emailAddress, languageCode, isActive, hireDate, dateOfLastHire and terminationDate.
- ServiceNow through the Import Set API (POST /api/now/import/{stagingTableName}/insertMultiple, asynchronous, with run_after for core_company, cmn_department and cmn_location before sys_user; coalesce on employee_number). Catalog requests through POST /api/sn_sc/servicecatalog/items/{sys_id}/order_now with sysparm_quantity, variables and sysparm_requested_for.
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in UKG Pro | Field in ServiceNow | Notes |
|---|---|---|
employeeId | employee_number | Coalesce key |
firstName, preferredName en lastName | first_name en last_name | |
emailAddress | email | |
companyId en companyName | company (core_company) | |
orgLevel1Code t/m orgLevel4Code | department (cmn_department) met parent | |
workLocation | location (cmn_location) | |
supervisorId | manager | |
alternateJobTitle of jobCode | title | |
languageCode | preferred_language | |
dateOfLastHire en terminationDate | Onboarding- en offboardingitem, active |
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