Oracle NetSuite and UKG integration

What moves between them

The main data flow is UKG into Oracle NetSuite. After each payroll period, ml-connector reads UKG's payroll GL journal export and posts the labor cost totals into NetSuite's general ledger, mapped to the departments and cost centers that match UKG's organizational structure. Employee records including hires, terminations, and role changes sync from UKG into NetSuite so headcount and department assignments remain aligned. Cost centers are validated against NetSuite's subsidiary and department hierarchy to ensure every GL posting lands on a valid account. Payroll GL data flows one direction only; NetSuite's ledger is not written back to UKG.

How ml-connector handles it

ml-connector stores both credential sets encrypted and manages the different authentication schemes: for UKG it uses HTTP Basic Auth plus the two custom API key headers (credentials cached to reduce UKG rate-limit exposure), and for Oracle NetSuite it uses OAuth 2.0 Client Credentials with token refresh every 55 minutes before expiry. Because neither system pushes payroll data automatically on a fixed schedule, ml-connector polls both UKG and NetSuite on a cadence aligned to your payroll calendar. Employee IDs in UKG are internal UUIDs, so ml-connector caches the ID-to-employee mapping and hydrates full profiles with a second call per employee on initial sync. Cost centers and departments are synced and validated in NetSuite before any GL posting is attempted, so every journal line lands on a GL account and department that exists. NetSuite's SuiteQL is used for bulk historical reads and to validate entity paths; UKG's delta endpoint reduces polling load on subsequent syncs. Every record carries a full audit trail and can be replayed if a downstream call fails.

A real-world example

A mid-sized consumer goods company runs Oracle NetSuite for operations, procurement, and finance, and uses UKG for payroll across three facilities and a shared services center. Before the integration, the accounting team exported payroll GL registers from UKG every month and manually re-entered labor cost lines into NetSuite, then spent the first week of close reconciling NetSuite headcount against UKG roster changes and fixing GL postings that landed on the wrong cost center. With Oracle NetSuite and UKG connected, each payroll cycle's GL journal flows into NetSuite automatically, routed to the cost center for each facility, and employee changes keep both systems aligned. Month-end close starts with labor accounts already reconciled, and the manual data entry and variance investigation are eliminated.

What you can do

• •Post UKG payroll GL journals into Oracle NetSuite's general ledger after every pay cycle, allocated to the correct cost centers and departments.
• •Keep Oracle NetSuite employee records synchronized with UKG hires, terminations, and rehires.
• •Validate UKG cost centers and departments against NetSuite's subsidiary and GL account structure so payroll lands on existing accounts.
• •Authenticate to UKG with HTTP Basic Auth and custom API headers, and to Oracle NetSuite with OAuth 2.0 Client Credentials with automatic token refresh.
• •Poll on a schedule tied to your payroll calendar, with retries, caching of UKG employee IDs, and a full audit trail on every record.

Questions

Which direction does data move between Oracle NetSuite and UKG?

The primary flow is UKG into Oracle NetSuite. Payroll GL journals and employee records move from UKG into NetSuite each pay cycle, while cost centers and departments are synchronized to ensure GL postings reference valid NetSuite accounts. Oracle NetSuite's general ledger is not written back to UKG; payroll GL data in UKG remains the source.

How does ml-connector handle the different authentication schemes for UKG and Oracle NetSuite?

ml-connector stores both credential sets encrypted. For UKG it uses HTTP Basic Auth with the two custom API key headers (US-CUSTOMER-API-KEY and US-USER-API-KEY), and for Oracle NetSuite it uses OAuth 2.0 Client Credentials, refreshing the OAuth token every 55 minutes before expiry to prevent outages. Both credentials are cached securely to reduce API rate-limit exposure.

Why does ml-connector need to make two calls per employee to UKG on initial sync?

UKG's employee ID endpoint returns only internal UUIDs. ml-connector calls the ID endpoint first to list all employees, then calls the full employee profile endpoint per UUID to hydrate demographic details, compensation, and department assignments. Delta polling on subsequent syncs uses a changed endpoint to reduce the fetch load after the initial pass.