.png)
UKG Dimensions Integration Guide
Integrate UKG Dimensions workforce data with enterprise applications through tenant-specific REST APIs, OAuth 2.0, scheduled workflows, and selected event or file-based mechanisms.
UKG Dimensions integration options at a glance
UKG Dimensions, increasingly positioned as UKG Pro Workforce Management, uses tenant-specific REST APIs as its primary integration mechanism. APIs can expose Employees, People, Locations, Schedules, Timecards, and Punches, subject to enabled products and permissions. OAuth 2.0 provides authenticated access, while selected UKG products or events may support notification or callback patterns. High-volume exchanges may use product-specific batch, asynchronous, import, export, or file capabilities rather than a universal bulk API. Martini can consume these endpoints, schedule incremental synchronization, map workforce data, expose normalized REST APIs, and apply validation, reconciliation, retry, and error-handling logic.
| Integration point | Supported by UKG Dimensions? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Retrieve and update Employees, People, Locations, Schedules, Timecards, and Punches where the tenant exposes the relevant resources. REST is the primary current integration mechanism. | Martini can consume UKG REST APIs, manage request sequencing and pagination, transform responses, and expose controlled APIs that abstract UKG-specific endpoints. |
| GraphQL APIs | Not confirmed | No official UKG Dimensions GraphQL API was confirmed in the available research. | Martini can consume GraphQL APIs generally, but a UKG GraphQL integration should not be designed without tenant-specific confirmation. |
| SOAP APIs | Not confirmed | No current UKG Dimensions SOAP API was confirmed as a recommended mechanism. Legacy interfaces require direct confirmation. | Martini can consume SOAP services when an applicable UKG interface is confirmed, but should not assume SOAP availability for this product. |
| Webhooks and outbound callbacks | Limited | Selected UKG products or events may provide event, notification, or callback capabilities, but universal change notifications for workforce objects were not confirmed. | Martini can receive confirmed UKG notifications and retrieve the current resource, or use scheduled REST synchronization when suitable events are unavailable. |
| Bulk, asynchronous, and batch processing | Limited | High-volume exchanges may use product-specific batch, export, import, asynchronous, or Integration Hub capabilities. A universal bulk REST API was not confirmed. | Martini can orchestrate batch jobs or process paginated API results, track checkpoints, reconcile totals, and route failed items for reprocessing. |
| File imports and exports | Limited | File-based workforce exchanges are used in some employee, schedule, time, accrual, and payroll-related scenarios, subject to the specific UKG product and tenant. | Martini can orchestrate approved file exchanges, parse and transform supported data, validate rows, and record file-level and item-level outcomes. |
| Authentication | Yes | UKG Pro Workforce Management integrations commonly use tenant-specific OAuth 2.0 credentials, token endpoints, permissions, and API configuration. | Martini can store secrets in protected configuration, obtain and reuse tokens, handle expiration, and apply environment-specific endpoint settings. |
| Database and analytics access | Not confirmed | Direct production database access should not be assumed. Reports, exports, APIs, and approved integration services are preferred for historical or analytical workloads. | Martini can consume approved API or export interfaces and write normalized results to an authorized target database, without depending on UKG production database access. |
How UKG Dimensions exposes data and business events
UKG REST APIs
UKG Pro Workforce Management REST APIs are the primary confirmed integration mechanism. The available resources and operations depend on the tenant, enabled API product, environment, and permissions assigned to the integration identity.
Martini implementation pattern
Martini implementation pattern: Martini authenticates with the customer’s OAuth 2.0 configuration, calls the applicable UKG resource, handles pagination and filters, maps the response to a canonical model, and writes or serves the result to downstream systems. Workflows can also submit approved updates where the tenant permits them.
Implementation sequence
UKG event notifications and callbacks
UKG event-oriented capabilities may exist for selected products or business events, but general-purpose webhook coverage for all Employees, Schedules, Timecards, and Punches was not confirmed. Availability, payload shape, delivery, and authentication must be verified for the tenant.
Martini implementation pattern
Martini implementation pattern: where a UKG notification or callback is confirmed, Martini receives the notification, validates its authenticity, and retrieves the current UKG resource when the event contains only an identifier. When no suitable event exists, a scheduler provides the reliable synchronization trigger.
Implementation sequence
UKG batch, export, and file exchanges
Some UKG workforce-management deployments use product-specific batch, asynchronous, import, export, Integration Hub, or file mechanisms for high-volume data. These capabilities are not a single universal bulk API and must be confirmed for the selected data domain.
Martini implementation pattern
Martini implementation pattern: Martini can initiate or consume an approved batch or file exchange, track the job or file checkpoint, validate records, transform workforce data, and produce reconciliation results. API pagination remains an alternative where no bulk mechanism is available.
Implementation sequence
UKG scheduled synchronization
Scheduled synchronization is an important fallback when event coverage is unavailable or when workforce data must be processed by payroll, approval, or reporting periods. It is suitable for Employees, Locations, Schedules, Timecards, and Punches where the selected APIs support retrieval.
Martini implementation pattern
Martini implementation pattern: a scheduler starts a workflow that retrieves changes using update timestamps, effective dates, or other supported filters. The workflow uses a durable watermark and overlap window, applies object-state rules, and upserts downstream data using stable UKG identifiers.
Implementation sequence
Common UKG Dimensions integration patterns
Pattern 1: Synchronize UKG employees with an HR or identity platform
When to use this pattern
Use this pattern when UKG Employees or People must be synchronized with Workday, Microsoft Entra ID, Salesforce, or an internal directory. It is appropriate for scheduled workforce changes when universal outbound events are not confirmed.
Integration direction
Example Mapping
| UKG Dimensions Field | Canonical Field | Target Field |
|---|---|---|
| employeeId | worker.sourceId | workerId or externalId |
| employmentStatus | worker.status | active or workerStatus |
| location | worker.locationCode | locationId |
| manager | worker.managerSourceId | managerId |
Martini implementation pattern
A scheduled Martini workflow retrieves Employees or People with pagination and an overlap window, matches existing workers by stable UKG identifiers, maps status and organizational fields, and applies rules for active, terminated, or incomplete workers. The workflow upserts the target, records outcomes, and routes authorization, validation, and downstream failures separately from retryable platform errors.
Martini capabilities used
- workflows
- API consumption
- OAuth 2.0 configuration
- data mapping
- business rules
- pagination and checkpoints
- error handling
Pattern 2: Send approved UKG timecards to payroll or an ERP
When to use this pattern
Use this pattern when approved or finalized Timecards, related Punches, Schedules, labor categories, and Locations must be sent to NetSuite, Workday, SAP S/4HANA, or Oracle Fusion Cloud HCM.
Integration direction
Example Mapping
| UKG Dimensions Field | Canonical Field | Target Field |
|---|---|---|
| timecardId | timeEntry.sourceId | externalTimeEntryId |
| employeeId | timeEntry.workerId | employeeId |
| totalHours | timeEntry.hours | quantity or hours |
| location | timeEntry.locationCode | location or costCenter |
Martini implementation pattern
Martini retrieves only the agreed approved or finalized state, preserves UKG Timecard and Punch identifiers, converts local dates and timestamps with timezone context, and maps labor and cost dimensions. A correlation store or deterministic key prevents duplicate payroll submissions; transient API failures are retried while validation and authorization errors are reconciled manually.
Martini capabilities used
- scheduled workflows
- API consumption
- data mapping
- date and timezone transformation
- idempotency
- business rules
- reconciliation
- retry handling
Pattern 3: Route UKG workforce exceptions to ServiceNow
When to use this pattern
Use this pattern when missing Punches, schedule exceptions, timecard approval issues, attendance alerts, or other selected workforce exceptions need operational ownership in ServiceNow.
Integration direction
Example Mapping
| UKG Dimensions Field | Canonical Field | Target Field |
|---|---|---|
| employeeId | exception.workerId | caller or employee reference |
| timecardId | exception.sourceReference | correlationId |
| exceptionType | exception.category | case or task type |
| status | exception.status | state |
Martini implementation pattern
A Martini workflow retrieves confirmed exception data through the relevant UKG API or notification mechanism, builds a stable correlation key from employee and source identifiers, and creates or updates the corresponding ServiceNow task. Business rules control severity and routing, while duplicate detection, safe logging, and retry classification protect the operational queue.
Martini capabilities used
- workflows
- API consumption
- event or scheduler triggers
- data mapping
- correlation and deduplication
- business rules
- error handling
Pattern 4: Expose a normalized UKG workforce API
When to use this pattern
Use this pattern when internal applications need current employee location, schedule, approved timecard status, or Punch history without receiving UKG credentials or learning tenant-specific API details.
Integration direction
Example Mapping
| UKG Dimensions Field | Canonical Field | Target Field |
|---|---|---|
| employeeId | workerId | request.employeeId |
| location | currentLocation | response.location |
| schedule | plannedShift | response.schedule |
| timecardStatus | approvedTimeStatus | response.timecardStatus |
Martini implementation pattern
Martini exposes a controlled REST API that validates the caller and request period, orchestrates one or more UKG REST calls, applies authorization and data-minimization rules, and returns a stable internal schema. The workflow can cache or normalize responses where appropriate and returns controlled errors without exposing UKG credentials or implementation details.
Martini capabilities used
- API exposure
- workflow orchestration
- API consumption
- authorization
- data transformation
- validation
- error handling
Applications commonly integrated with UKG Dimensions
UKG Dimensions workforce data can be coordinated with HR, identity, ERP, service-management, and operational applications. The appropriate direction depends on which system owns worker, schedule, time, or exception data.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Workday | Align worker, organization, location, employment, schedule, time, and absence information across HR and workforce-management processes. | Workday → Martini → UKG Dimensions | Martini can retrieve worker or organizational changes from Workday, call UKG REST APIs, and separately synchronize approved UKG time or schedule data back to Workday. Workflows apply source-of-truth rules, identifier matching, field mapping, and reconciliation. |
| ServiceNow | Create cases, tasks, or operational alerts for missing punches, schedule exceptions, timecard approval issues, and other workforce exceptions. | UKG Dimensions → Martini → ServiceNow | A scheduled or confirmed event-driven workflow retrieves selected UKG exceptions, creates or updates ServiceNow records using a stable correlation key, and routes validation or downstream failures for review. |
| Salesforce | Provide employee, availability, location, or field-workforce information to customer-service and field-service processes. | UKG Dimensions → Martini → Salesforce | Martini can retrieve approved UKG workforce data, normalize employee and location identifiers, apply data-minimization rules, and upsert Salesforce data while preserving source identifiers and processing status. |
| NetSuite | Transfer approved labor, time, and workforce-cost data into finance and ERP processes. | UKG Dimensions → Martini → NetSuite | Martini retrieves finalized Timecards and related Punches or labor attributes, maps them to NetSuite employee, department, location, and accounting dimensions, and prevents duplicate submissions with correlation records. |
| SAP S/4HANA | Coordinate workforce time, labor, organizational, and cost data with enterprise finance and operations. | UKG Dimensions → Martini → SAP S/4HANA | A Martini workflow retrieves approved UKG data, transforms workforce and cost attributes into the SAP target model, applies cutoff and status rules, and records reconciliation totals and rejected items. |
| Oracle Fusion Cloud HCM | Synchronize worker, organization, time, attendance, and absence information across HR and workforce-management processes. | Oracle Fusion Cloud HCM → Martini → UKG Dimensions | Martini orchestrates worker-data and time-data flows in the agreed direction, maps IDs and effective dates, handles pagination and overlap windows, and separates authorization, validation, and transient failures. |
| Microsoft Entra ID | Provision, update, or deprovision workforce identities based on employment status and organizational information. | UKG Dimensions → Martini → Microsoft Entra ID | Martini can retrieve eligible Employees or People, apply employment-status and minimization rules, and invoke the identity platform while retaining a source-to-target correlation and audit result. |
| Jira | Create work items for workforce-management integration failures, reconciliation exceptions, or operational issues. | UKG Dimensions → Martini → Jira | Martini classifies UKG and downstream failures, creates or updates Jira issues using a deterministic key, includes safe diagnostic context, and avoids exposing unnecessary employee data in issue descriptions. |
How to build a UKG Dimensions integration in Martini
Objective
Establish tenant-specific UKG and target-system configuration without embedding credentials in workflows.
Instructions in Martini
- Confirm UKG tenant URLs, API products, OAuth client details, scopes, and permissions.
- Store client secrets, token settings, and environment-specific endpoints in protected configuration.
- Configure target-system authentication separately and verify connectivity in a non-production environment.
Objective
Select a trigger that matches UKG event availability, processing frequency, and workforce business deadlines.
Instructions in Martini
- Use a scheduler for reliable periodic synchronization when outbound event coverage is unavailable.
- Use a confirmed UKG notification or callback only for explicitly supported products and events.
- Use an API trigger when an internal application needs an on-demand workforce response.
Objective
Read the required UKG objects while controlling volume, state, and time context.
Instructions in Martini
- Retrieve Employees, People, Locations, Schedules, Timecards, or Punches from the applicable REST resources.
- Implement pagination, supported change filters, durable watermarks, and overlap windows.
- Preserve UKG identifiers, local dates, timestamps, offsets, and object status.
Objective
Coordinate retrieval, enrichment, validation, target writes, and outcome recording in one maintainable integration flow.
Instructions in Martini
- Separate authentication, retrieval, transformation, business rules, target writes, and reconciliation logic.
- Use reusable workflow components for common pagination, token, correlation, and error behavior.
- Route records according to approval, employment, schedule, or exception status.
Objective
Convert UKG workforce objects into the canonical and target models required by downstream systems.
Instructions in Martini
- Map stable source identifiers before display fields.
- Normalize organization, location, labor, status, and manager values.
- Handle local timezone, overnight shifts, payroll periods, and UTC conversions without losing source context.
- Validate required fields and distinguish Punches from finalized Timecards.
Objective
Ensure only eligible and authorized workforce data is processed downstream.
Instructions in Martini
- Process only agreed Timecard states, such as approved or finalized.
- Apply source-of-truth rules for Employees, People, Locations, schedules, and time data.
- Minimize sensitive employee and location fields in payloads, logs, and downstream systems.
- Use deterministic correlation keys to make retries idempotent.
Common UKG Dimensions data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Employees | Workforce members whose employment, organizational, location, and time-related data is managed by UKG. | Workday, Microsoft Entra ID, Salesforce, Oracle Fusion Cloud HCM | Martini retrieves Employees with pagination and change filters where available, maps stable identifiers and status fields, and upserts downstream users or worker profiles. |
| People | Person profiles and identity-related workforce information used to represent individuals in the workforce. | Workday, Microsoft Entra ID, Salesforce | Martini applies data-minimization and identity-matching rules, preserves UKG identifiers, and separates person-profile processing from employment-state processing when required. |
| Locations | Physical or organizational work locations used for assignments, scheduling, attendance, and labor management. | Workday, Salesforce, NetSuite, SAP S/4HANA | Martini normalizes location codes, timezones, and organizational relationships before mapping them to target location or accounting dimensions. |
| Schedules | Planned shifts and scheduled work assignments for employees and locations. | Workday, Salesforce, internal workforce applications, SAP S/4HANA | Martini retrieves schedules for a defined period, preserves local business dates and timezone context, and applies overlap and deduplication rules. |
| Timecards | Recorded and calculated employee time used for approval, payroll, workforce management, and cost processing. | NetSuite, Workday, SAP S/4HANA, Oracle Fusion Cloud HCM | Martini processes only the agreed status, retains source status and identifiers, maps labor and cost attributes, and prevents duplicate downstream submissions. |
| Punches | Clock-in, clock-out, transfer, and other time-entry events associated with Timecards. | Workday, ServiceNow, payroll applications, internal time systems | Martini treats Punches as source time events rather than automatically finalized payroll results, preserves local time context, and correlates them to Timecards and Employees. |
Authentication and security considerations
OAuth 2.0 and tenant configuration
UKG Pro Workforce Management integrations commonly use tenant-specific OAuth 2.0 credentials, token endpoints, API base URLs, permissions, and enabled API products. The exact grant type, scopes, audience, and token URL should be confirmed for the customer environment.
Secrets and permissions
Store client secrets and token responses in protected configuration rather than embedding them in workflows. A valid OAuth client may still receive authorization failures if its integration user, service account, role, or tenant configuration lacks access to a resource.
Workforce data protection
- Minimize employee, time, attendance, and location fields to the business requirement.
- Protect logs and error payloads from unnecessary personal information.
- Separate development, test, and production credentials and endpoints.
- Apply appropriate retention, access control, and audit requirements.
Operational considerations for UKG Dimensions integrations
Pagination and incremental synchronization
Employee, schedule, timecard, punch, and location collections can be large. Implement pagination, supported change filters, durable watermarks, and a small overlap window for late updates.
Time and workforce state
Preserve tenant and location timezones, offsets, business dates, overnight shifts, and daylight-saving transitions. Do not treat a Punch as a finalized payroll result; define which Timecard states are eligible for downstream processing.
Reliability and reconciliation
- Confirm current UKG rate limits and control concurrency.
- Use exponential backoff for transient failures and handle HTTP 429 responses if returned.
- Use stable UKG identifiers and correlation keys to prevent duplicate writes.
- Retry transient platform failures, but route validation and authorization failures for review.
- Monitor API version and schema changes, including fields, enums, and required attributes.
- Maintain reconciliation totals and processing statuses for bulk or historical exchanges.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration instead of isolated scripts
Martini provides a maintainable workflow layer for authentication, pagination, transformation, business rules, target writes, reconciliation, and error handling. This avoids duplicating UKG-specific logic across separate scripts and applications.
Controlled API access
Martini can expose normalized REST APIs so internal applications do not need UKG credentials or tenant-specific knowledge. It can validate requests, apply authorization and minimize returned data before calling UKG.
Operational consistency
- Use reusable workflows for token handling, checkpoints, mapping, correlation, and retries.
- Combine scheduled, API-led, event-oriented, and file-based processing where appropriate.
- Centralize monitoring, diagnostics, reconciliation, and deployment configuration.
- Extend transformation or business logic with custom code only where required.
Frequently asked questions
UKG Dimensions, increasingly positioned as UKG Pro Workforce Management, can be integrated primarily through tenant-specific REST APIs authenticated with OAuth 2.0. Depending on the product and tenant, integrations may also use selected event notifications, callbacks, batch or asynchronous capabilities, file imports or exports, and scheduled synchronization. The available Employees, People, Locations, Schedules, Timecards, and Punches resources depend on API products and permissions.
Yes. Martini can integrate with UKG Dimensions by consuming the applicable UKG REST APIs, authenticating with the customer’s OAuth 2.0 configuration, scheduling synchronization workflows, mapping workforce objects, exposing normalized REST APIs, and receiving selected UKG notifications or file exchanges where the tenant explicitly supports them.
No. A dedicated UKG Dimensions connector is not required. Martini can use UKG’s confirmed native integration mechanisms, including REST APIs, OAuth 2.0 authentication, scheduled workflows, and any tenant-specific event, callback, batch, export, import, or file capabilities that are enabled.
Lonti does not charge an additional per-connector or per-vendor fee to integrate UKG Dimensions. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from UKG, cloud infrastructure, or other third-party systems depending on subscription, usage, and deployment model.
REST APIs are the primary confirmed method for current UKG Pro Workforce Management integrations. Use scheduled synchronization for dependable batch or incremental processing, and evaluate product-specific batch, asynchronous, import, export, or file mechanisms for high-volume workloads. GraphQL and current SOAP support were not confirmed and should not be assumed.
Selected UKG products or events may provide notifications, callbacks, or other event-oriented capabilities, but universal webhook coverage for all workforce objects was not confirmed. The event type, payload, delivery behavior, authentication, and tenant availability should be verified before using an event-driven design. Martini can use scheduled REST synchronization when no suitable event is available.
Martini can retrieve Timecards and Punches when the customer’s UKG API permissions expose those resources. The workflow should distinguish raw Punches from approved or finalized Timecards, preserve UKG identifiers and local timezone context, use incremental filters where available, and apply idempotent upsert and reconciliation behavior.
Yes. Martini can expose a controlled REST API that validates callers, orchestrates UKG REST API requests, applies authorization and data-minimization rules, and returns a stable internal schema. This allows internal applications to access approved workforce data without receiving UKG credentials or depending directly on tenant-specific UKG implementation details.
Related Martini documentation
Workflows
Plan your UKG Dimensions integration
Connect UKG Dimensions to HR, identity, ERP, service-management, and internal applications with Martini workflows, APIs, secure configuration, and reliable synchronization patterns.