What This Is

This is not a thin OpenAPI wrapper.

This server is designed to behave like a UKG Pro WFM reasoning layer. It accepts natural language, determines what the user is really asking, resolves missing inputs, discovers the correct API path, hydrates partial objects, traverses references, validates completeness, scores confidence, and returns full operational answers.

Core Rule

Search and list endpoints are discovery only. They are not final truth.

If an API response contains IDs, references, partial objects, child references, parent references, profile references, or linked configuration, the server must hydrate those objects before answering.

Execution Model

Capabilities

Capability	Purpose
Natural language routing	Understands operational questions without requiring endpoint knowledge
Missing input resolution	Finds IDs, refs, dates, employees, groups, profiles, and related objects
Discovery-only enforcement	Prevents list/search responses from being treated as final truth
Universal hydration	Pulls full detail for every reachable partial object
Object graph traversal	Follows parent, child, profile, group, org, and setup references
Completeness validation	Calculates whether the answer is complete enough to return
Confidence scoring	Classifies answers as CERTAIN, HIGH, MEDIUM, LOW, or BLOCKED
Write safety	Requires hydration, dry-run, explicit confirmation, and re-read after writes
Audit logging	Records source chain, duration, confidence, and affected objects

Supported Domains

Domain	Coverage Intent
Attendance	Events, patterns, and attendance-related operational context
Common Resources	Shared objects, lookup values, Hyperfinds, and common references
Employee Self Service	Employee-facing objects and request flows
Forecasting	Forecast-related workforce planning data
Healthcare Productivity	Productivity and staffing context
HCM	HCM-connected workforce data
Leave	Leave cases, requests, balances, and related context
People	Person, employee, manager, job, and org details
Person Assignments	Assignments, roles, and workforce relationships
Platform	Tenant, metadata, and platform-level capabilities
Scheduling	Schedules, shifts, coverage, and schedule analysis
Scheduling Setup	Scheduling configuration and setup references
Timekeeping	Timekeeping objects and operational time data
Timekeeping Setup	Pay rules, work rules, pay codes, and setup metadata
Timekeeping Timecards	Timecards, punches, exceptions, totals, approvals
Timekeeping Bulk Operations	Controlled bulk workflows with guardrails
Universal Device Manager	Device and clock-related operational context
Webhook Events	Event subscriptions and event payload normalization

Hydration Behavior

Traditional API result:

Server behavior:

This applies to every object type, not just Known Places.

Confidence Levels

Level	Meaning
CERTAIN	Unique immutable identifier, full hydration, no unresolved dependencies, no conflicts
HIGH	Strong candidate, full target detail, minor non-critical references unavailable
MEDIUM	Likely answer, but some relevant references remain unresolved
LOW	Ambiguous or incomplete
BLOCKED	Cannot proceed safely because required data, access, or endpoint is unavailable

Architecture

Execution Pipeline

Primary Tool

ukg_wfm_ask

Use this for natural language requests.

Examples:

Write Safety

Every write operation follows the same lifecycle:

Write, delete, and bulk operations cannot execute from:

name-only matches
search results
partial objects
inferred identities
ambiguous references

Only fully hydrated targets are eligible for mutation.

Installation

Clone the repository:

Install dependencies:

Configure environment:

Required environment variables:

Start development server:

Build production:

Run tests:

Scorecard

Generate endpoint intelligence and risk outputs:

Outputs:

docs/endpoint-scorecard.json
docs/tool-risk-matrix.json

Project Goals

This project exists to eliminate three common problems in workforce management integrations:

Partial answers
Manual endpoint selection
Missing relationship awareness

The server's responsibility is not merely to call APIs.

Its responsibility is to understand the request, discover what information is missing, retrieve that information, validate it, and return the most complete answer possible from the available system of record.