Sage X3 and UKG integration

What moves between them

The main flow runs from UKG into Sage X3. After each payroll run, ml-connector reads UKG's GL payroll journal export and posts labor cost journals into X3's general ledger, mapped to the matching X3 GL accounts and cost centers. Employee records flow the same direction so X3 headcount reflects UKG hires, terminations, and status changes. Cost centers, pay groups, and compensation details are polled from UKG on each sync cycle and mapped to X3 supplier master and cost allocation records. GL journals are read-only in UKG, so ml-connector never writes financial entries back to payroll.

How ml-connector handles it

ml-connector stores both credential sets encrypted and refreshes Sage X3 bearer tokens on each API call since they expire every 5 minutes, while caching UKG OAuth2 tokens within their 1-hour window. On the Sage X3 side it accepts the full customer-specific server URL, port, and folder name from your instance, since X3 publishes no shared hostname. On the UKG side it authenticates with either HTTP Basic Auth and API key headers or OAuth2 depending on your UKG edition and API tier. Because neither system pushes payroll events natively, ml-connector polls on a schedule tied to your payroll calendar, reading UKG employee and GL records and writing them to X3 as supplier master entries and GL postings. Cost centers and departments are mapped first so every payroll journal line references an X3 GL account and cost center that already exists. UKG's employee-ids endpoint returns only internal UUIDs, requiring a second call per employee to fetch the full profile, which ml-connector handles as a two-pass fetch on initial sync. Every record carries a full audit trail and can be replayed if a downstream write fails.

A real-world example

A mid-sized manufacturing company with plants in multiple locations runs Sage X3 for supply chain and finance and UKG Workforce Now for payroll and time and attendance. Before the integration, payroll analysts exported UKG pay registers and GL journals each pay period and manually re-entered labor costs into X3 by plant and cost center, then spent days during month-end reconciling X3 headcount against UKG employee records. With Sage X3 and UKG connected, each payroll run's GL journal flows into X3 automatically and allocated to the correct plant cost centers, and employee changes keep headcount in sync. Month-end close starts with labor accounts already reconciled and the manual data entry step is eliminated.

What you can do

• •Post UKG payroll GL journals into Sage X3 general ledger after every pay run, allocated to the correct cost centers and GL accounts.
• •Keep Sage X3 employee master data aligned with UKG hires, terminations, and status changes.
• •Map UKG cost centers, pay groups, and compensation to Sage X3 GL dimensions and supplier cost allocations.
• •Authenticate Sage X3 with OAuth2 or HTTP Basic Auth and refresh 5-minute bearer tokens on each batch, and UKG with HTTP Basic Auth and API key headers or OAuth2.
• •Poll on a schedule tied to your payroll calendar, with two-pass employee fetch, retry logic, and a full audit trail on every record.

Questions

Which direction does data move between Sage X3 and UKG?

The main flow is UKG into Sage X3. Payroll GL journals and employee records move from UKG into X3, while cost centers and compensation details are read from UKG on each sync. GL journals are read-only in UKG, so ml-connector does not write financial entries back to payroll.

Why does ml-connector need to handle Sage X3 token refresh differently from UKG?

Sage X3 bearer tokens expire every 5 minutes, requiring a refresh on each API call. UKG OAuth2 tokens expire in 1 hour, so ml-connector caches them within that window and only refreshes when approaching expiry. This difference is why ml-connector manages each side separately.

What is the two-pass employee fetch on UKG, and why is it necessary?

UKG's /personnel/v1/employee-ids endpoint returns only internal UUID identifiers. A second call per employee to /personnel/v1/employees/{id} is required to fetch the full employee profile with demographics and compensation. ml-connector handles both calls transparently on initial sync to build the complete employee master in Sage X3.