The problem this solves

Oracle EPM Planning stores the financial truth for a mid-to-large enterprise — income statement, balance sheet, cash flow — updated on a daily or weekly cycle by planning and close operations. The data is correct. The problem is retrieval.

A finance analyst who wants "Berlin Mitte's Q3 FY26 net revenue vs Plan" opens Oracle SmartView, authenticates, navigates to the right cube, sets five POV dimensions, builds or finds a row set, pulls the data, and copies it to a deck. On a good day that is 6 minutes. On a day with a VPN problem or an expired token it is 25 minutes and two IT tickets.

The NLQ layer changes the retrieval to a typed sentence. The analyst types "Show me Berlin Mitte Q3 FY26 revenue vs plan" and sees the table in under 4 seconds. The insight work — the comparison, the narrative, the flag to the CFO — starts immediately.

Audience

FP&A analysts, finance managers, and CFOs who run Oracle EPM Planning and spend meaningful time each period on data retrieval rather than analysis. Revenue management teams tracking actuals vs plan by entity and period. EPM architects evaluating whether to add an NLQ layer to an existing PBCS or EPBCS deployment.

Natural language financial queries

Input is a plain-text string entered by the finance user. No syntax to learn. The parser resolves the query against five EPM dimension axes:

Minimum viable query: statement type + entity. All other dimensions default: Scenario → Plan, Year → FY26, Period → all four quarters.

A structured financial table with BvA variance

The output is a rendered financial table in the browser:

• Row dimension: Account members grouped by statement section (Revenue, COGS, Gross Profit, OpEx, EBIT…)
• Column dimension: Period(s) × Scenario(s), up to 8 columns
• BvA column: Actual − Plan, colour-coded green/red with ↑↓ directional arrows
• Chart: bar, line, doughnut, radar, waterfall, stacked, ranking, or combo — selected by LLM or overridden by user

Secondary outputs

• Downloadable Excel file with Oracle SmartView HsGetValue formulas pre-populated and a Connection Guide sheet
• JSON export of the raw data object (for pipeline integration)

In your EPM workflow

This use case lives between data entry / close operations (which write to EPM) and management reporting (which reads from EPM). It does not replace Oracle Analytics Cloud for enterprise BI — it replaces the ad-hoc retrieval that currently falls to SmartView or manual PBCS grid navigation.

Recommended integration points

• CFO review prep: Controller types 5 queries in 2 minutes to populate a review deck, replacing 30 minutes of SmartView grids
• Variance triage: Business partner types "Show Toronto actual vs plan Q2 FY26" the moment a variance alert fires
• Month-end close: Accountant verifies a line item against plan before posting a journal entry
• Board pack prep: IR team generates 44 store-level IS tables in one session without touching SmartView

The numbers

The honest checklist

• ✓You have Oracle EPM Planning (PBCS, EPBCS, or Planning Modules) in production with a financial data model
• ✓Your finance team does more than 20 ad-hoc data retrievals per person per week
• ✓You can expose a read-only EPM REST API endpoint — or you want to start with the demo data layer first
• ✓Your users are comfortable with a browser UI (no SmartView client install required)
• ✗You need real-time writeback or plan input — NLQ is read-only by design
• ✗You have fewer than 5 EPM data consumers — the LLM overhead isn't justified at that scale
• ✗You need row-level security per user without building an EPM REST API auth layer

Try it now

The live demo runs on pre-loaded EPM demo data with a real DeepSeek LLM call for every query.

Sample queries to try

• "Show income statement for Berlin Mitte FY26"
• "Toronto Q3 actual vs plan"
• "APAC balance sheet FY25"
• "Cash flow forecast FY26 waterfall chart"

The value calculation

A 6-minute retrieval task done 20 times per analyst per week = 2 hours/analyst/week. For a 10-person FP&A team that is 20 hours/week — half an FTE per period spent on getting data rather than using it.

At a loaded cost of $120K/year for a mid-level FP&A analyst, the retrieval overhead costs $60K/year for that team. The NLQ layer at DeepSeek pricing costs ~$108/year at 100 queries per day — a 555:1 cost ratio in favour of the AI layer.

The secondary business case is accuracy. Manual SmartView retrieval introduces two error modes: wrong POV selection (wrong entity or period) and copy-paste errors into decks. NLQ-generated output is deterministic for a given input — the same query always returns the same table. The only remaining error mode is query ambiguity, which surfaces as an explicit error state rather than a silent wrong number.

Three-layer pipeline

The key design decision: Layer 2 defines a clean contract that works identically whether the data comes from the demo corpus or a live EPM REST API call. Switching to production means replacing one function — the data resolver — without touching the parser or renderer.

App UI — Component breakdown

UI state machine

Idle → Loading (LLM call in flight, submit disabled, spinner visible) → Result (table + chart rendered) → Error (scoped message + 4 sample query links). Error state never shows a raw stack trace — only a user-readable message pointing to valid query patterns.

EPM dimension corpus

Account hierarchy — 55 members

Other dimensions

• Store/Entity (44): Total Company → North America (12 stores incl. NYC Flagship, LA Beverly Hills, Toronto) · EMEA (10 stores incl. London Oxford St, Berlin Mitte, Dubai Mall) · APAC (9 stores incl. Tokyo Shibuya, Shanghai Plaza, Mumbai BKC) · LAD (5 stores incl. Sao Paulo, Buenos Aires) · Digital (5: US/EMEA/APAC/LAD Digital + Global Marketplace) · Corporate (3: HQ, Distribution, Franchise)
• Scenario (6): Plan, Actual, Forecast, Budget, Latest Estimate, Prior Year Actual
• Year (5): FY23, FY24, FY25, FY26, FY27
• Period (4): Q1, Q2, Q3, Q4 — plus synthetic full-year aggregation, seasonally weighted for Q4 holiday peak

System prompt structure

The system prompt has four parts:

1. Role definition: "You are an Oracle EPM Planning NLQ parser. Return ONLY valid JSON…"
2. Output schema: Strict JSON definition with field names, types, and enum values for every dimension
3. Dimension enums: Exhaustive lists of valid entity names, scenarios, years, periods, statement types, and chart types — prevents hallucination outside the known corpus
4. Few-shot examples: 12 query → JSON pairs covering IS/BS/CF, multi-period (H2, YTD), multi-scenario (plan vs actual), region rollup, and chart type selection

Guard clause

If the query cannot be mapped to an EPM query, the LLM returns {"error": "out_of_scope"}. The app renders a specific error message with sample queries — it never tries to answer a non-EPM question with EPM data.

// Truncated system prompt excerpt
You are an Oracle EPM Planning NLQ parser.
Return ONLY this JSON (no markdown, no prose):
{
  "statementType": "IS" | "BS" | "CF",
  "entity": <one of: NYC Flagship, LA Beverly Hills, Toronto,
              London Oxford St, Berlin Mitte, Dubai Mall,
              Tokyo Shibuya, Shanghai Plaza, Mumbai BKC,
              Sao Paulo, Buenos Aires, US Digital, ... (44 total)>,
  "scenario": "Plan" | "Actual" | "Forecast" | "Budget" | "LE",
  "year": "FY22" | "FY23" | "FY24" | "FY25" | "FY26",
  "periods": [ "Q1" | "Q2" | "Q3" | "Q4" ],
  "chartType": "bar" | "line" | "doughnut" | "radar"
               | "waterfall" | "stacked" | "ranking" | "combo"
}

How we measure accuracy

Eval set: 120 hand-written query → expected JSON pairs covering all dimension combinations, edge cases (two scenarios in one query, implicit entity via region, month names), and out-of-scope adversarial inputs.

Cost per query

DeepSeek V3 pricing as of Aug 2026: $0.14 per 1M input tokens, $0.28 per 1M output tokens. Prices subject to change — verify at platform.deepseek.com/docs/pricing.

Cost model — At-scale projections

SmartView licence estimates are illustrative Oracle list prices. NLQ does not replace SmartView for power users who need writeback, zero-suppression, or complex member selection — it adds a fast-access retrieval layer for read-heavy users who currently misuse SmartView as a lookup tool.

Key files and their roles

Critical implementation detail

The DeepSeek API is OpenAI-compatible. The nlq-query.js function uses fetch against https://api.deepseek.com/chat/completions with model: "deepseek-chat" and response_format: { type: "json_object" } — this forces structured JSON output and eliminates markdown-wrapped responses. Validate the output against the schema before using it; a malformed response triggers the offline fallback.

Tech stack — Every tool in this build

Known attack surfaces

Guardrails — What we built to prevent bad outputs

• Schema validation: LLM JSON output is validated against the expected schema before use. Invalid output (missing fields, wrong enum values) triggers the offline fallback parser — not an error state.
• Dimension enum enforcement: Entity, scenario, year, and period values are checked against their known enum before the data resolver runs. An unknown entity returns "No data found" rather than a wrong number.
• Out-of-scope detection: Queries that don't resolve to a valid EPM statement return a specific user-readable message with sample queries. The message never says "I don't understand" — it says "I help with Oracle EPM data — try: …"
• Offline fallback: If the DeepSeek API is unavailable, a rule-based parser handles a subset of fixed-format queries at zero cost. Clearly labelled as fallback mode in the UI.
• Input length limit: Query input capped at 500 characters. Longer inputs are truncated before reaching the LLM.

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: Planning User, plus access to the Financials cube and the relevant forms.

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 the Entity and Account dimensions — read / write / none per member per group. This is the row-level control that decides whether a store manager sees one store or forty-four.
• 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 FP&A NLQ

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 FP&A NLQ 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 FP&A NLQ

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