> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kronos Workforce Central

> Connect Kronos Workforce Central (UKG WFC) to Serval so workflows can call the WFC XML API — timekeeping, schedules, people data — with the cookie-session logon handled automatically.

## 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

| Capability                    | Description                                                                                                                                                                                                                                                                                        |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Kronos XML API request action | Send any Workforce Central XML request envelope from a workflow and get the raw XML response back, with the session established automatically. The per-object vocabulary (Timesheet, Punch, Person, Schedule, …) is documented in UKG's Developer's Toolkit reference guides for your WFC version. |
| Connection health checks      | Three built-in checks: credentials and session establishment (with per-cause failure diagnosis), the identity the session authenticates as, and the WFC server's clock and time zone.                                                                                                              |

## 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](mailto: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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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).
  </Step>

  <Step title="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`.
  </Step>
</Steps>

## Connect in Serval

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Username">
    The dedicated WFC account with XML API access.
  </Step>

  <Step title="Password">
    The account's password. Stored encrypted; used only by Serval's backend to establish the WFC session.
  </Step>
</Steps>

<Note>
  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.
</Note>

## 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:

```xml theme={null}
<Kronos_WFC Version="1.0">
  <Request Action="Load">
    <Timesheet>
      ...
    </Timesheet>
  </Request>
</Kronos_WFC>
```

<Warning>
  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.
</Warning>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Never include Logon or Logoff in your envelopes">
    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.
  </Accordion>

  <Accordion title="The connection fails with a redirect error">
    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.
  </Accordion>

  <Accordion title="Credentials are right but the logon is rejected">
    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.
  </Accordion>

  <Accordion title="The logon succeeds but no session cookie arrives">
    A proxy or load balancer in front of WFC may be stripping Set-Cookie headers. Serval needs the logon response's cookies verbatim to authenticate follow-up calls.
  </Accordion>

  <Accordion title="A request fails with a session error">
    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.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Kronos Workforce Central integration.