Microsoft Dynamics 365 Business Central and UKG integration

What moves between them

The main flow runs from UKG into Microsoft Dynamics 365 Business Central. After each payroll run, ml-connector reads UKG third party pay distributions and posts the labor cost lines into Business Central general ledger journals, mapped to the matching GL accounts and dimensions. Employee records flow the same direction so Business Central reflects UKG hires, terminations, and rehires. Reference data such as cost centers and departments is aligned so payroll allocations land on valid Business Central dimensions. The Business Central chart of accounts is read only, so ml-connector reads accounts to validate mappings and never writes accounts back into Business Central or payroll back into UKG.

How ml-connector handles it

ml-connector stores both credential sets encrypted and presents the UKG Basic Auth plus customer and user API key headers on every call, while obtaining and refreshing the Business Central Entra ID token when a call returns 401. On the Business Central side it accepts the tenant ID, client ID, client secret, and environment name per customer, since the environment name is part of the URL, and it builds the company scoped path from those values. UKG does not expose journal entries over REST, so labor distributions are read from the third party pay service and reconstructed into Business Central journal lines, each referencing a GL account and dimension that already exists. Cost centers are mapped to Business Central dimensions before any posting runs. UKG core REST is offset paginated by page and per_Page up to 200, and employee profiles need a two pass fetch because the IDs endpoint returns only UUIDs, so the connector collects IDs first then fans out. Both sides return HTTP 429 when throttled, so ml-connector backs off with jitter and retries. Where UKG webhooks are enabled it verifies the HMAC signed payload and reads the changed employee, but because UKG events expire after 14 days it also polls the changed employees endpoint so nothing is lost during an outage.

A real-world example

A regional healthcare group with about 900 staff across several clinics runs Microsoft Dynamics 365 Business Central for finance and uses UKG for payroll and scheduling. Before the integration, the finance team exported a payroll register from UKG every pay period and keyed the labor totals into Business Central by hand, then spent the first days of month-end close chasing differences between clinic headcount and the wage accounts in the ledger. With the two systems connected, each payroll run's pay distributions flow into Business Central general ledger journals automatically, allocated to the dimension for each clinic, and employee changes keep the two systems aligned. Month-end close starts with the wage accounts already reconciled, and the manual re-keying step is gone.

What you can do

• •Post UKG payroll pay distributions into Microsoft Dynamics 365 Business Central general ledger journals after every pay run, allocated to the correct accounts and dimensions.
• •Keep Business Central employees aligned with UKG hires, terminations, and rehires using the changed employees delta endpoint.
• •Map UKG cost centers and departments to Business Central dimensions so payroll lands on valid accounts.
• •Authenticate UKG with Basic Auth plus customer and user API keys, and Business Central with Microsoft Entra ID OAuth2 tokens.
• •Poll on a schedule tied to your payroll calendar, with backoff on HTTP 429 and a full audit trail on every record.

Questions

Which direction does data move between Microsoft Dynamics 365 Business Central and UKG?

The main flow is UKG into Business Central. Payroll pay distributions and employee records move from UKG into Business Central, while cost centers and dimensions are aligned so postings are valid. The Business Central chart of accounts is read only and UKG holds no financial entries to receive, so ml-connector does not write accounts back to Business Central or payroll back to UKG.

How does the integration get payroll GL data out of UKG when there is no GL REST endpoint?

UKG does not expose journal entries or a GL accounts endpoint over REST. ml-connector reads the third party pay distributions, which carry debit, credit, account, and cost center fields, and reconstructs them into Business Central general ledger journal lines. Each line is mapped to a GL account and dimension that already exists in Business Central before the journal is posted.

How are the two different auth schemes and the webhook retention window handled?

ml-connector stores both credential sets encrypted. It sends the UKG Basic Auth header with both the customer and user API keys on every call, and obtains a Microsoft Entra ID OAuth2 token for Business Central, refreshing it on a 401. Because UKG webhook events are retained for only 14 days, the connector also polls the UKG changed employees endpoint so no change is lost if the endpoint is down.