Skip to main content

​
About Kronos Workforce Central

Kronos Workforce Central (now UKG Workforce Central) is a self-hosted workforce management suite covering timekeeping, scheduling, accruals, and attendance. Its API is the Developer’s Toolkit XML gateway: a single endpoint (/wfc/XmlService) that accepts XML request envelopes for every operation. WFC authenticates with a session cookie: a Logon call returns a JSESSIONID cookie that every subsequent call must present. Serval performs that logon server-side and injects the session cookie into each request automatically — workflow authors never send credentials, never handle cookies, and never include Logon/Logoff requests in their envelopes. Authentication: A dedicated WFC account with XML API (Developer’s Toolkit) access. Serval logs on server-side, maintains the session, and re-establishes it as needed. Sessions are reused for a few minutes at a time, so bursts of workflow calls share one logon instead of each performing their own. Data sync: On demand only. There is no background sync and no pre-built workflows; reads and writes happen inside workflow runs, and three health checks verify the connection.

​
What the Kronos integration enables

​
Expose Workforce Central to Serval

WFC is self-hosted, so Serval must be able to reach your XML gateway over HTTPS:
  • Expose the gateway (typically via a load balancer) and allow inbound traffic from Serval’s egress IPs — contact support@serval.com for the current list.
  • The host you expose must forward Set-Cookie headers from WFC unchanged. If your load balancer adds its own affinity cookies, Serval replays them together with the WFC session cookie automatically.
  • Point the gateway directly at the WFC XML service. An SSO or portal front that redirects the logon request will fail the connection with a redirect error.

​
Get your credentials

1

Create or choose a dedicated WFC account

Use a dedicated service account (for example, serval-integration) rather than a person’s login, and exempt it from password-expiration policies if possible — if the password rotates, the connection fails until it is updated in Serval.
2

Grant XML API access

The account’s Function Access Profile must permit XML API / Developer’s Toolkit access, plus access to the data your workflows will touch (for example, timekeeping for Timesheet requests).
3

Note your gateway host

The hostname (and optional port or path prefix) where /wfc/XmlService is reachable from the internet, e.g. kronos.example.com or lb.example.com/kronos.

​
Connect in Serval

1

Open the Kronos Workforce Central connect form

In Serval, add the Kronos Workforce Central integration to open the connect form. All three fields are required.
2

Gateway Host

The host where your WFC XML gateway is reachable — no https://. A port or path prefix is allowed: kronos.example.com, kronos.example.com:8443, or lb.example.com/kronos. The host is lowercased; a path prefix keeps its exact case.
3

Username

The dedicated WFC account with XML API access.
4

Password

The account’s password. Stored encrypted; used only by Serval’s backend to establish the WFC session.
When you reopen the connection to edit it, the saved password appears masked. Leaving it untouched keeps the stored password, so you can change the host or username without re-entering it.

​
Verifying the connection

Test Kronos Connection — authenticates and completes a System Ping over the established session.
  • Pass: “Successfully authenticated with Workforce Central and completed a System Ping over the session.”
  • Fail: the message surfaces the server-side logon diagnosis, which distinguishes the possible causes — an unreachable host, a redirect (an SSO or portal front), an answer that isn’t a Workforce Central XML envelope (wrong host or path), or rejected credentials with WFC’s own error code.
Verify Session Identity — loads the logged-on account’s identity (CurrentUser LoadIdentities), confirming the session authenticates as the expected service account and that basic API function access (API.Common) is granted.
  • Pass: “The session authenticates as person number [number].”
Check Server Time — reads the WFC server’s date, time, and time zone (ServerTime GetServerTime). For a timekeeping system, clock skew or an unexpected server time zone silently corrupts punch data — this check makes it visible.
  • Pass: “Workforce Central server time is [date and time] ([time zone]).”

​
Using the XML API from workflows

Send a complete Kronos_WFC envelope and check each Response element’s Status attribute:
WFC answers HTTP 200 even for failed requests — the outcome is the Status attribute (Success or Failure) on each <Response> element, with detail in <Error> elements (ErrorCode, Message). Workflows must check Status, not the HTTP status.

​
Gotchas and troubleshooting

Serval establishes and maintains the session automatically. An envelope containing a Logon request would carry credentials workflow code should never hold — leave authentication to the connection.
The gateway host must point directly at the WFC XML service. A redirect on logon usually means the host is an SSO front or a portal path — expose /wfc/XmlService directly instead.
Verify the account’s Function Access Profile actually permits XML API (Developer’s Toolkit) access — a valid password without API access is still rejected. The connection error includes WFC’s own error code and message when the gateway provides one.
Serval reuses each session for a few minutes and then logs on again, so a stale session heals itself within moments. If an app-server restart or an admin session purge lands mid-window, the next few calls can see a WFC session error before the refresh — retrying the workflow step succeeds.
Need help? Contact support@serval.com for assistance with your Kronos Workforce Central integration.