UKG Pro

Overview

The UKG Pro WFM plugin syncs workforce-management data from your UKG Pro WFM tenant into Snowflake using the Omnata Sync Engine. It is an inbound-only plugin — data flows from UKG Pro into Snowflake tables.

---

Prerequisites

Before creating a connection you will need:

1. A UKG Pro WFM tenant with API access enabled.

2. A service account (username + password) in UKG Pro with at least read access to the timekeeping, scheduling, and commons data APIs.

3. An API application registered in UKG Pro (see the Authentication section below for the values you will need to collect).

For step-by-step instructions on registering an API application and locating the connection parameters, refer to the UKG Pro WFM API Quick Start guide and the UKG Developer Portal authentication documentation.

---

Authentication

UKG Pro WFM uses OAuth 2.0 with a password-realm grant. You will need to collect the following values before creating the Omnata connection. These come from two places: your UKG tenant configuration and the API application you register in UKG.

Value	Where to find it
API Host	Your tenant hostname — visible in your browser's address bar when logged into UKG Pro (e.g. mytenant.npr.mykronos.com)
Token URL	The base URL of the OAuth token endpoint for your tenant — typically the same origin as the API host (e.g. https://mytenant.npr.mykronos.com)
Client ID	Generated when you register an API application in UKG Pro
Client Secret	Generated alongside the Client ID when you register the API application
Audience	The API audience value for your tenant, provided during application registration. Typically a URL like https://wfm.ukg.net/api
Realm	The authentication realm for your tenant (e.g. UltiPro) — found in your UKG tenant settings
Username / Password	The service account credentials used to authenticate against the API

Access tokens are automatically refreshed by the plugin during long syncs — you do not need to manage token expiry yourself.

---

Connection Setup

Navigate to Connections → New Connection and select UKG Pro WFM. Fill in the following fields using the values collected above:

Field	Description	Example
API Host	Your UKG tenant hostname (without https://)	mytenant.npr.mykronos.com
Token URL	Base URL for the OAuth token endpoint	https://mytenant.npr.mykronos.com
Client ID	OAuth application client ID	abc123
Client Secret	OAuth application client secret (stored encrypted)	—
Username	Service account username	svc_omnata
Password	Service account password (stored encrypted)	—
Audience	OAuth audience value	https://mytenant.npr.mykronos.com
Realm	Authentication realm	UltiPro

When you save, Omnata will test the connection by verifying that the credentials can authenticate and reach the UKG timekeeping API. A failure here typically means the service account lacks read permissions or one of the credential fields is incorrect.

---

Sync Configuration

When creating or editing an inbound sync, the following options are available:

Option	Default	Description
Start date	2022-01-01	The earliest date to pull data from on the very first (full-refresh) sync. Ignored for incremental syncs, which use the last-sync timestamp instead.
Detect deletes via audit logs	Off	When enabled (timecards stream only), the plugin queries UKG audit logs for Delete events and marks the corresponding timecard records as deleted in Snowflake.

Tuning parameters

Parameter	Default	Description
Fetch batch size (rest_batch_size)	500	Number of employee identifiers sent per API batch request. Reduce this if you encounter timeouts or payload-size errors.

---

Data Streams

employees

Employee demographics fetched via the UKG commons data API. All employees returned by the All Home hyperfind are included.

Sync strategy: Full refresh only. Primary key: id (the UKG employee identifier).

Key columns:

Column	Description
id	Unique employee identifier
EMP_COMMON_FULL_NAME	Full name
EMP_COMMON_PRIMARY_JOB	Primary job title
EMP_COMMON_PRIMARY_ORG	Primary organisation path
PEOPLE_EMP_STATUS	Employment status (e.g. Active, Inactive)
PEOPLE_HOME_COST_CENTER	Home cost centre
PEOPLE_HIRE_DATE	Hire date
PEOPLE_BADGE_NUMBER	Badge number
PEOPLE_FIRST_NAME	First name
PEOPLE_LAST_NAME	Last name
PEOPLE_BIRTH_DATE	Date of birth
PEOPLE_PERSON_NUMBER	HR person number ("Employee ID")
PEOPLE_HOME_LABOR_CATEGORY	Home labour category
PEOPLE_PAYRULE	Pay rule name
PEOPLE_ACCRUAL_PROFILE_NAME	Accrual profile
PEOPLE_EXPECTED_DAILY_HOURS	Expected daily hours
PEOPLE_EXPECTED_WEEKLY_HOURS	Expected weekly hours
PEOPLE_EXPECTED_PAYPERIOD_HOURS_NEW	Expected pay-period hours

The plugin first attempts to fetch all columns (core + extended). If the extended keys are not supported by your tenant, it falls back automatically to the core columns only so the stream always succeeds.

---

timecards

Raw timecard objects from the UKG timekeeping API. Each row represents one employee's timecard for a given date-chunk window.

Sync strategies: Full refresh, Incremental. Primary key: id (composite: employee_qualifier|chunk_start_date). Cursor field: last_modified_timestamp.

The nested UKG response structure is stored as-is (semi-structured). For row-level analysis, use the timecard_spans stream instead.

Incremental behaviour

On incremental syncs the plugin checks which employees had timecard changes since the previous sync. Only those employees are re-fetched, reducing API load significantly on large tenants.

Delete detection

When Detect deletes via audit logs is enabled, timecard records whose employee has a delete audit event in the sync window are emitted with a delete flag to Snowflake, instructing the Omnata runtime to remove that row from the destination table.

---

timecard_spans

The timecard_spans stream processes the same timecard data as the timecards stream and flattens it into one row per span or pay-code edit. This produces a much more query-friendly tabular shape.

Sync strategies: Full refresh, Incremental. Primary key: id / WORKITEMID — a 16-character deterministic hash based on employee_qualifier + apply_date + pay_code + transaction_id. Cursor field: last_modified_timestamp. Depends on: timecards (must be enabled in the same sync).

Two source types are merged into this single stream:

Source	IS_PAYCODE_EDIT
Calculated spans (day totals)	false
Manual pay-code edits	true

Key columns:

Column	Description
id / WORKITEMID / UNIQUE_KEY	Deterministic row identifier
EMPLOYEE_NUMBER	Employee qualifier
APPLYDATE	Date the row applies to (YYYY-MM-DD)
SPAN_START_DATE_TIME	Span start timestamp
SPAN_END_DATE_TIME	Span end timestamp
PUNCH_IN	Earliest in-punch of the day
PUNCH_OUT	Latest out-punch of the day
PAY_CODE_NAME	Pay code qualifier
PAYCODETYPE	Pay code type
TOTAL_WORK_TIME_IN_HOURS	Hours for this span
DAYS	Days for this span
ESTIMATED_WAGE	Estimated wage
WORKRULE	Work rule qualifier
WORKED_JOB	Transferred job qualifier
WORKED_COST_CENTER	Transferred cost centre qualifier
SPAN_LABOR_CATEGORIES	Labour category qualifier
IS_PAYCODE_EDIT	true when row comes from a manual pay-code edit
IS_HISTORICAL	true for historical correction entries
HISTORICAL_DATE	Date of the historical correction
HISTORICAL_HOURS / HISTORICAL_DAYS / HISTORICAL_WAGE	Historical correction amounts
TIMECARD_TRANSACTIONID	UKG transaction ID (stable across syncs when present)
FILEUPDATEDATETIME	Timecard last-modified timestamp

---

schedules

Schedule data from the UKG scheduling API. Each shift is flattened into one row per segment; shifts with no segments produce a single row keyed on the shift itself.

Sync strategies: Full refresh, Incremental. Primary key: id / TIMEITEMID — segment ID from UKG or a deterministic hash. Cursor field: last_modified_timestamp.

Key columns:

Column	Description
id / TIMEITEMID	Segment identifier
SHIFTASSIGNID	Parent shift identifier
EMPLOYEE_NUMBER	Employee qualifier
APPLYDATE	Date portion of segment start (YYYY-MM-DD)
SHIFT_SEGMENT_START_TIME	Segment start timestamp
SHIFT_SEGMENT_END_TIME	Segment end timestamp
PAYCODENAME	Pay code qualifier
PAYCODETYPE	Pay code type
HOURS	Segment duration in hours
SHIFT_SEGMENT	1-based segment index within its parent shift
SHIFTTYPE	Shift type from UKG
TRANSFERED_COST_CENTER_CODE	Transferred cost centre
TRANSFERED_JOB	Transferred job qualifier
LABOR_CATEGORY	Labour category
WORKRULE	Work rule qualifier
WORKED_SALARY_CLASSIFICATION	Salary classification for the worked job
FILEUPLOADEDDATETIME	Parent shift last-modified timestamp

Deleted shifts are propagated to Snowflake so Omnata removes them from the destination table.

---

workload_planner

Staffing demand data from the UKG workload planner. One row is produced per (location, date, span_name, job) combination.

Sync strategies: Full refresh, Incremental. Primary key: id — a 16-character deterministic hash based on location + date + span_name + job. Cursor field: last_modified_timestamp.

Location auto-discovery: Rather than requiring you to enumerate locations manually, the plugin reads employees' primary organisation paths and derives the unique leaf location paths automatically before fetching workload planner data.

Key columns:

Column	Description
id	Deterministic row identifier
LOCATION	Organisation path used to scope the query
DATE	Date for this row (YYYY-MM-DD)
SPAN_NAME	Workload span name (e.g. HSO 0800-1606)
SPAN_TYPE	WORKLOAD or COVERAGE
SPAN_START_TIME	Span start time
SPAN_END_TIME	Span end time
JOB	Organisational job qualifier (full org path with role as the last segment)
BUDGET	Budgeted headcount
PLAN	Planned headcount
ACTUAL	Scheduled (actual) headcount

---

Incremental Sync

All streams except employees support incremental syncs. On each run:

1. The plugin uses the stored last_modified_timestamp state to determine what has changed since the previous sync.

2. For timecards and timecard_spans, only employees with timecard changes since the last sync are re-fetched, keeping API usage proportional to actual change volume.

3. Date ranges are chunked into a maximum of 30 days per API request to avoid payload size limits.

---

Troubleshooting

Symptom	Likely cause	Resolution
Connection test fails with an authentication error	Incorrect credentials or wrong Token URL / Realm	Double-check all eight connection fields against your UKG application settings
Connection test fails with a permissions error	Service account lacks read access to the timekeeping module	Grant the service account appropriate API read permissions in UKG Pro
employees stream returns core columns only, missing PEOPLE_PERSON_NUMBER etc.	Extended data dictionary keys not licensed/enabled on tenant	The plugin falls back automatically; contact UKG support to enable extended keys
workload_planner returns no rows	No leaf location paths could be derived from employee org fields	Verify employees have primary organisation values with at least two path segments
Timeouts or server errors on large tenants	Batch size too large	Reduce Fetch batch size to 100–200
Deleted timecards not being removed from Snowflake	Delete detection is disabled	Enable Detect deletes via audit logs in the sync configuration