The problem this solves

Workforce is usually the second module implemented after Financials, and the one with the most sensitive data. It plans headcount and the full cost of employing people — salary, additional earnings, benefits and taxes — across every store, distribution center, and corporate function.

The hard part is not the arithmetic. It is that a retailer's workforce is enormous and heterogeneous: 44 stores each staffed differently by format, a distribution network with union labor, seasonal headcount that doubles in November, and sales roles with commission on top of base pay. Getting the default cost structure right for every job — once — is what makes the module usable. Getting it wrong means every planner overrides at the employee level, which defeats the point and inflates data volume.

Audience

HR business partners and FP&A teams who own headcount and compensation planning. EPM architects choosing Workforce granularity before a design workshop. Anyone who has been asked "why is Sales Associate showing Headcount 1 when Store B only has half a person scheduled there?"

A store, a year, and a scenario

Pick a store/entity, year, and scenario. The demo generates the store's staffing plan from a format-based template (Flagship, Standard, Digital, DC, Corporate, Franchise) — each job seeded with an FTE count, some of them deliberately fractional (0.75, 4.25) to exercise the rounding rule in the next section.

Headcount, FTE, and fully-loaded cost by job

• Table: Job × Pay Type × Union × FTE × Headcount × Base × Benefits × Taxes × Earnings × Fully-Loaded Cost
• Cascade panel: click any job row to see exactly which components — 401(k) match, health insurance, payroll tax, bonus, commission, seasonal premium — apply, and their computed cost
• KPI row: Total Headcount, Total FTE, Fully-Loaded Cost, Average Cost per FTE
• Guardrail demo: a button injects a record mapped to the OWP_All Jobs scope member and shows the double-benefit trap being caught before it reaches the plan

Between HR data and the P&L

Workforce sits between the HR feed (source of truth for who works where) and Financials (which absorbs Store Labor, Corporate Labor, and DC Labor as OpEx lines). It is not a payroll system — it plans the cost, payroll executes it.

Recommended integration points

• Budget cycle kickoff: HRBP reviews each store's job template and adjusts FTE before compensation defaults are applied
• Seasonal planning: Store ops adds Temporary employee-type FTE for Nov–Dec, priced with Seasonal Premium Pay automatically via the job default
• Compensation review: Finance checks fully-loaded cost per job against the retail P&A of Store Labor and Store Occupancy accounts already in the FP&A module
• Union negotiation prep: DC Workers Union and Retail Workers Union costs are isolated by filtering on Union Code

The numbers

The honest checklist

• ✓You plan headcount and compensation across enough stores/jobs that employee-by-employee overrides are already a problem
• ✓You can define clean default cost structures by job, union, or similar grouping — the module runs itself once defaults are right
• ✓Your retail business has seasonal headcount swings that need modeling (Temporary employee type, Seasonal Premium Pay)
• ✓You need a member-level security design for who can see salaries — cost centre managers seeing only their own team is a common ask
• ✗You need real payroll processing — this plans cost, it does not run payroll
• ✗Job-only granularity is enough and you never need Split-Funded FTE or Merit Based Planning — those features require Employee or Employee and Job granularity, so confirm the feature list before the design workshop

Try it now

The live demo runs entirely client-side — pick a store, click a job row, and toggle the All_ member trap simulator.

Things to try

• Type "Payroll for the distribution network" into the NLQ bar and watch it resolve entity, year, and scenario in one step
• Switch to LA Beverly Hills (Flagship) vs a Standard-format store and compare total headcount
• Click Visual Merchandiser — note 0.75 FTE still shows Headcount 1
• Click Simulate the All_ member trap and watch the guardrail fire

Why defaults are the whole game

A retailer with 44 stores and 22 job types has on the order of a thousand FTE positions. Pricing each one by hand is not viable. Assign benefits, taxes, and earnings by job — or union code, or a similar grouping — rather than employee by employee. Get the defaults right and the module largely runs itself; get them wrong and planners override at employee level, which is exactly the manual effort the module exists to remove.

The demo makes this concrete: change JOB_DEFAULTS['J_SM'] once in the data layer and every Store Manager FTE across all 44 stores recalculates. That single-point-of-change property is what Synchronize Defaults does in a real EPBCS application when an entity default changes.

Staffing template → cascade → cost

This is a genuinely separate module — a new data file, epm-workforce-capex-data.js, loaded alongside (not instead of) epm-data.js. It reuses ENTITIES for store format and region but adds nothing to the FP&A/SmartView/Analytics/Master Data cube. Zero risk to the first four use cases.

App UI — Component breakdown

Employee, Job, or Employee and Job

Granularity is chosen at enablement and is the defining Workforce decision. Three options: Employee, Job, or Employee and Job. Feature dependencies constrain the choice — Split-Funded FTE and Merit Based Planning both require Employee or Employee and Job granularity. If merit planning is on the requirements list, Job-only was never viable; check the feature list against granularity before the design workshop, not after.

The common pattern, and the one this demo models conceptually, is Employee and Job: the bulk of the population planned at Job level (this demo's store staffing), with employee detail reserved for senior or specialist roles. Employee and Job does not oblige loading employee records for everyone — that is a separate volume decision.

Union Code has an escape hatch: if a client doesn't track union codes, the dimension can be renamed to something meaningful — but a default must still be assigned to the renamed dimension. This demo keeps the real name and adds an explicit No Union member rather than leaving the field blank.

The configuration workhorse

This is the exact mechanism section 3.3 of the Workforce framework describes as "the configuration workhorse." JOB_DEFAULTS in the data layer is a direct analogue of an EPBCS entity default assignment: one row per job, listing which components apply and at what rate. genWorkforce() looks up the job's defaults and prices each line against that job's base cost — %-of-base components (401(k), bonus, commission, payroll tax) scale with FTE and pay; flat-per-head components (health insurance, uniform, vehicle allowance) scale with headcount, not FTE, matching how EPBCS treats per-employee benefits.

Retail-specific defaults worth noting: Sales Associate and Senior Sales Associate carry a 1.5% Sales Commission component that Cashier does not (commission attaches to roles that drive sales, not to transaction processing). Delivery Driver carries a Vehicle Allowance that no other job has. Seasonal Premium Pay is assigned to every customer-facing store job (Sales Associate, Cashier, Stockroom, Visual Merchandiser) to model November–December holiday staffing economics.

Two numbers that legitimately diverge

Headcount is the actual number of employees, and is always 1.0 for any employee whose FTE is greater than 0. FTE is full-time equivalent, where full-time is 1.0. FTE rounds to the nearest integer for headcount purposes — except values greater than 0 and less than 1, which always round up to 1.

FTE 0.25   →  Headcount 1.0    (rounds up, not to 0)
FTE 1.25   →  Headcount 1.0    (rounds to nearest)
FTE 4.75   →  Headcount 5.0    (rounds to nearest)

The demo's Visual Merchandiser row at a Standard-format store is staffed at 0.75 FTE — deliberately, so the rule is visible without reading documentation: Headcount still shows 1. fteToHeadcount() is a four-line function, but it is the single most support-ticket-generating behaviour in a live Workforce module. Explain it in training, or answer it every planning cycle.

The All_ member trap — Why some seeded members are not data locations

These members exist to define a default-assignment scope — "this benefit applies to all jobs" — not as a place an employee record can live. The usual root cause is a data load mapping blank values to the All_ member as a catch-all, because it looks like a safe default. It is the opposite of safe: it silently doubles cost.

The demo's Simulate the All_ member trap button injects exactly this bad record — a workforce row with jobId: 'OWP_All Jobs' — and runs it through checkAllMemberTrap(), a guardrail that flags any record whose job or union is a scope member before it reaches the plan. The general lesson generalizes past Workforce: in any EPM module, some seeded members are configuration scope rather than data locations, and the All_ naming pattern is the tell. Before mapping a source value to a seeded member, ask what that member is for.

The correct fix for a genuine blank is not a catch-all — it's an explicit member. That's why this demo's Union Code dimension has a real No Union member instead of leaving the field empty.

Defaults vs Definition — the distinction that matters most

Entity DEFAULTS = which components apply to whom → Synchronize Defaults. Component DEFINITION = the component's own rates and properties → Synchronize Definition. Choosing the wrong one is the classic Workforce support call: you changed a pension rate, ran Synchronize Defaults, and nothing moved — because the assignment didn't change, the definition did.

Both Process Loaded Data with… rules are self-sufficient — no additional rule is needed afterwards to compute compensation. Both also set Headcount to 1 and Partial Payment Factor to 100% for every employee unless different values were loaded at the processing month, which is exactly the demo's fteToHeadcount() behaviour reproduced at the rule level. Pre-24.12 applications use the older-named equivalents (Synchronize Defaults, Synchronize Component Definition, Calculate Compensation, Calculate Employee/Job Compensation for All Data, Process Loaded Data) — Oracle recommends updating to the 24.12+ rules.

Groovy templates behind the menus

Workforce ships Groovy templates behind menu items and on-save actions — OWP_Add Requisition_GT, OWP_Change Salary_GT, OWP_Incremental Synchronize Defaults_GT, and others. Security must be set on them or the menu items fail for users. The four Incremental templates implement the dirty-cell pattern — processing only changed data on save, the same idea behind this demo's cascade panel recalculating only the clicked job rather than the whole table.

Key files

NLQ prompt design

Workforce's query schema is intentionally the smallest in the whole prompt: {"intent":"workforce_query","entity":"<name|null>","year":"<FY26|FY25>","scenario":"<Plan|Actual>","confidence":<0-1>}. There is no job, union, or component field to extract — those are explored interactively by clicking a table row, not by asking for them in the query. Keeping the LLM's job to entity/year/scenario resolution (the same three fields FP&A and Currency Translation extract) keeps the prompt cheap and the failure surface small; the mechanism-heavy parts of this demo — the rounding rule, the cascade, the All_ trap — stay deterministic client-side logic, untouched by the LLM.

Tech stack — Every tool in this build

Known attack surfaces

Guardrails — What prevents bad workforce plans

• Rounding rule enforced once, centrally: fteToHeadcount() is the only place headcount is derived — no page computes it independently, so the rule can never drift out of sync across views.
• All_ member guardrail: any record whose job or union resolves to a scope member is flagged with the specific remediation (assign a real job and union; use "No Union" for genuine blanks) rather than a generic error.
• Explicit blank handling: the Union Code dimension has no implicit default — every employee record must carry No Union or a real union, never a blank.
• Single-point default changes: changing a job's compensation defaults changes it everywhere that job is staffed, in one edit — the same design goal as Synchronize Defaults in production EPBCS.

Who is asking, and what are they allowed to see?

The demo answers neither question — it has a cookie gate and no notion of a user. In production these are the two questions everything else rests on, and they have different answers: authentication is who you are, authorization is what you may see. Corporate SSO settles the first. Only Oracle EPM Cloud can settle the second, and the single most important rule in this section is that this application must never become the place where that decision is made.

9.1 · The identity chain, end to end

9.2 · Federating the corporate identity provider

Oracle EPM Cloud does not replace your directory — it trusts it. The EPM Cloud identity domain is federated with the corporate IdP so authentication happens where it already happens, under policies security has already written.

For the browser application itself, use OIDC Authorization Code flow with PKCE. Not the implicit flow, which is deprecated and leaks tokens through the URL, and never a resource-owner password grant — a finance tool should not be capable of handling a password at all.

9.3 · From group membership to EPM roles

Roles are granted to groups, never to individuals, and the groups come from the directory. That one discipline is what makes joiner/mover/leaver work without anyone having to remember this application exists.

Entra ID group                    →  EPM role / entitlement
──────────────────────────────────────────────────────────────────
FIN-EPM-Analysts                  →  Planning User
FIN-EPM-Controllers-EMEA          →  Power User + EMEA data scope
FIN-EPM-Admins                    →  Service Administrator
──────────────────────────────────────────────────────────────────
Provisioned by SCIM. Remove the user from the group and the
entitlement disappears on the next sync — including here.

For this use case the relevant native entitlement is: EPBCS Workforce User, plus a separate HR/compensation entitlement for employee-level pay.

9.4 · The architectural decision: who enforces?

This is the choice that determines whether the deployment is defensible. Both patterns appear in the diagram above; the difference is where the security boundary actually sits.

The shortcut to refuse. Pattern B built with a Service Administrator account and no filtering at all is the most common way this gets delivered, because it works perfectly in UAT — testers are usually over-entitled, so nobody notices that everyone can see everything. It fails at the first access review, and by then it is in production with real users depending on it.

9.5 · Data-level security is the part that matters

Role membership decides whether a user can open the application. It does not decide which rows they get back, and confusing the two is the most expensive mistake available here.

• For this use case: Planning access permissions on Entity and a second gate on the compensation accounts — two independent checks, because entity access does not imply salary access.
• Apply it before aggregation, not after. Filtering a total that has already been computed across entities the user cannot see still leaks the total.
• The NLQ layer needs its own check. Layer 4 already validates that the resolved point of view uses approved members; production adds a second test — that the resolved POV sits inside this user’s scope — and it runs before the data call, not after. A natural-language interface is very good at asking for things politely; the authorization check must not care how the question was phrased.
• Fail closed. If entitlements cannot be resolved, return nothing and say so. An empty result is a support ticket; a permissive default is an incident.

9.6 · Provisioning, sessions and the leaver problem

• SCIM provisioning from Entra or Okta into the EPM Cloud identity domain (OCI IAM, formerly IDCS), covering joiner, mover and leaver. The mover is the case people forget — somebody changing region should lose the old scope, not accumulate both.
• No local user store. If this application keeps its own copy of who may do what, a leaver keeps access until somebody remembers to update it. Nobody ever does.
• Short-lived access tokens with refresh-token rotation; align session timeout with the data classification rather than with convenience.
• MFA and Conditional Access at the IdP — not reimplemented here. Device compliance and location policy come free with federation.
• Quarterly recertification of both the groups that grant access and the service account’s own entitlements, evidenced and signed.
• Break-glass access is a named, monitored, time-boxed account — never a shared credential in a password manager.

9.7 · What this means for Workforce Planning

9.8 · Security configuration checklist

• ✓Oracle EPM Cloud federated with the corporate IdP over SAML 2.0 or OIDC; the cookie gate removed entirely
• ✓Browser app uses OIDC Authorization Code + PKCE — no implicit flow, no password grant
• ✓MFA and Conditional Access enforced at the IdP, not reimplemented in the application
• ✓Roles granted to directory groups, never to individuals; SCIM covers joiner, mover and leaver
• ✓Enforcement pattern chosen deliberately — Pattern A where the API supports it, or Pattern B with filtering centralised and tested
• ✓Data-level security applied before aggregation, and the resolved POV checked against the user’s scope before the data call
• ✓No local user table and no local role table anywhere in the application
• ✓Every query logged against the real end user, even when a service account makes the call
• ✓Authorization failures fail closed and are logged as security events rather than swallowed
• ✓Quarterly recertification of access groups and of the service account’s own entitlements

From demo to a governed enterprise deployment

Everything above runs on synthetic data, a public LLM API key, a cookie gate, and no audit trail — deliberately, so the mechanics are inspectable. Taking Workforce Planning to production is not a rewrite; the 4-layer pipeline and the data-layer contract survive intact. It is a controlled-change program across six workstreams: architecture, LLM platform, security, SOX/audit, environment promotion, and operations. This section is the checklist we run with clients.

10.1 · Production reference architecture

10.2 · Choosing the LLM platform

The demo’s DeepSeek call is a placeholder for a single adapter, callLLM(system, user), behind Layer 3. Swapping the provider changes one function and zero business logic. Pick the platform the organisation already governs — the security and procurement review is the long pole, not the integration.

Put a model gateway in front of whichever you choose (Azure API Management, OCI API Gateway, Kong AI Gateway, LiteLLM, or Portkey): it owns key custody, per-team spend caps, routing and fallback between models, prompt/response logging, and lets you retire a deprecated model without touching the application.

10.3 · Security controls

10.4 · SOX, audit, and model-risk controls

A read-only NLQ layer does not change a financial-reporting control, but it is an interface to a SOX-relevant system and lands squarely in ITGC scope. Treat prompts, schemas, and eval sets as code — that single decision satisfies most of what an auditor will ask for.

10.5 · Dev → Test → Prod promotion

• Promoted artifacts: application build, prompt templates (versioned), approved-member schema snapshot, eval set, infrastructure config (IaC) — all from the same Git tag.
• Pipeline: branch → PR review → CI (tests + evals) → deploy to Test → UAT sign-off → CAB → deploy to Prod → smoke test. Hosting can stay on Cloudflare Pages/Workers or move to OCI Functions + API Gateway or the org’s standard platform — the code does not care.
• Configuration: per-environment secrets and endpoints injected at deploy; the same build runs in every environment.
• Metadata sync: a scheduled job refreshes dimension metadata into Layer 2 grounding with change detection, so a new entity or account appears in the approved lists without a code release.
• Rollback: previous build and previous prompt version retained; rollback is a redeploy, and because prompts are versioned it also reverts a prompt regression.

10.6 · Operating it

• SLOs: p95 latency, availability of the read path (the deterministic fallback keeps it alive when the LLM is down — already built), fallback rate as a quality signal, eval pass rate per release.
• Cost governance: per-user and per-team token budgets at the gateway; alert on anomalies; the unit-cost model earlier in this kit is the baseline.
• Model lifecycle: providers retire models on a schedule — re-run the eval suite on the successor before switching, and record the switch as a change.
• Incident runbook: LLM outage → fallback parser; EPM API outage → cached metadata with a stale banner; guardrail spike → review logs for injection attempts.

10.7 · What changes for Workforce Planning

10.8 · Production readiness checklist

• ✓LLM platform selected from the governed list, DPA / zero-retention terms on file, gateway in front of it
• ✓SSO integrated; authorisation derived from EPM security groups; cookie gate removed
• ✓Read-only EPM service account per pod, credential in a vault, rotation scheduled
• ✓Prompts, schema, and eval set version-controlled and under change management
• ✓Append-only audit log wired to the SIEM with the agreed retention
• ✓Golden-query eval suite passing in CI; results archived as release evidence
• ✓Dev / Test / Prod pipeline with gates, IaC, and a rehearsed rollback
• ✓Model-risk register entry and owner named; first re-validation date set
• ✓Metadata refresh job scheduled with change detection
• ✓SLOs, cost caps, and the incident runbook agreed with platform operations