326 lines
21 KiB
Markdown
326 lines
21 KiB
Markdown
---
|
|
name: knowledge-one-view-cli
|
|
description: Fetch Oracle Analytics LAD Knowledge One View sales data directly through Oracle DV APIs instead of scraping the browser UI. Use when Codex needs opportunity details, pipeline and close-date data, revenue-line analysis, SR details, fiscal-year or session context, or ad hoc Oracle DV queries for the Sales Intelligence Knowledge One View workbook at `salesintelligence-dv.oracle.com`.
|
|
---
|
|
|
|
# Knowledge-One-View-CLI
|
|
|
|
Use the direct API path first. Read only the smallest reference needed, run the shortest matching command, and open Chrome only when direct auth or workbook tracing requires it.
|
|
|
|
## Quick Navigation
|
|
|
|
- Need the complete consolidated skill documentation:
|
|
[docs/docs.html](docs/docs.html)
|
|
- Need manager, hierarchy, architect-productivity, or team-rollup business context:
|
|
[references/initial-context-catalog.md](references/initial-context-catalog.md)
|
|
- Need the explicit annual `week` lookup such as `w2`, `w43`, or `week 43`:
|
|
[references/script-catalog.md#week-reference](references/script-catalog.md#week-reference)
|
|
- Need the exact CLI surface, flags, or script contract:
|
|
[references/script-catalog.md](references/script-catalog.md)
|
|
- Need traced endpoints, workbook defaults, or view reconstruction details:
|
|
[references/api-map.md](references/api-map.md)
|
|
- Need a migration checklist for a new computer:
|
|
[portable-setup.md](portable-setup.md)
|
|
|
|
## Core Rules
|
|
|
|
- Use `scripts/fetch-sales-intelligence.mjs` for normal backend reads.
|
|
- Do not use REPL, browser scraping, or workbook rendering calls for routine retrieval.
|
|
- Open Chrome only when direct auth is blocked or the workbook trace must be refreshed.
|
|
- Prefer the fewest steps that still produce a correct answer.
|
|
- Choose exactly one execution mode per fetch call: `--intent`, `--view`, `--query`, or `--sql`.
|
|
- Prefer instructions already encoded in the local catalogs over re-deriving Oracle fields by hand.
|
|
|
|
## Trigger Cues
|
|
|
|
Use this skill when the request is about any of these:
|
|
|
|
- LAD Knowledge One View opportunity or SR data
|
|
- close-date pipeline windows or month/day close-date asks
|
|
- pipeline, opportunity, won, close-window, territory, or owner analysis from Knowledge DV - Opportunities - V2
|
|
- hours or hierarchy analysis from Knowledge DV - Hours - V2
|
|
- presales coverage or involvement from Knowledge DV - Presales Involvement Aux - V1
|
|
- Oracle DV fiscal-year/session variables used by the workbook
|
|
- ad hoc Oracle logical SQL or alias-based query mode against the workbook data
|
|
- manager hierarchy, architect productivity, or team rollups tied to these datasets
|
|
|
|
## Fast Path
|
|
|
|
1. Decide whether the ask is a manager or hierarchy ask.
|
|
2. If it is, read [references/initial-context-catalog.md](references/initial-context-catalog.md) first.
|
|
3. If the ask uses `week`, `wk`, or `w1`..`w5`, read [references/script-catalog.md#week-reference](references/script-catalog.md#week-reference) first.
|
|
4. If auth may be stale, run `--check-auth`.
|
|
5. Execute the shortest matching path immediately:
|
|
- recurring business ask -> `--intent`
|
|
- known extract -> `--view`
|
|
- ad hoc aliases, filters, grouping, ordering -> `--query`
|
|
- only if query mode cannot express it cleanly -> `--sql`
|
|
6. Read [references/script-catalog.md](references/script-catalog.md) or run `--catalog` only when one contract detail is still unknown.
|
|
7. Read [references/api-map.md](references/api-map.md) only when API behavior changed or a workbook view must be retraced.
|
|
|
|
## Preferred Execution Order
|
|
|
|
### 1. Intents
|
|
|
|
Use intents first for recurring business asks.
|
|
|
|
- `opportunities-default`
|
|
Use as the canonical default for generic opportunity and pipeline retrieval on Knowledge DV - Opportunities - V2.
|
|
- `opportunities-close-date`
|
|
Use for one exact close date with `--date`.
|
|
- `opportunities-close-month`
|
|
Use for one calendar month with `--month`.
|
|
- `opportunities-close-quarter`
|
|
Use for one fiscal quarter with `--quarter`, including `current-quarter`.
|
|
- `opportunities-current-team-close-window`
|
|
Use for asks that really mean current-team coverage, such as allocated-resource manager, people attached through SR work, or similar team-involvement wording. This intent keeps the full org-wide opportunity/workload window and only enriches resource fields from the current team.
|
|
- `opportunities-by-resource-close-window`
|
|
Use when the ask names one explicit resource and you need opportunities in a close-date window tied to that person through coverage data, with commercial fields coming from Knowledge DV - Opportunities - V2.
|
|
- `opportunities-by-manager-close-window`
|
|
Use when the ask names one explicit manager email and you need opportunities in a close-date window tied to that hierarchy anchor, with commercial fields coming from Knowledge DV - Opportunities - V2.
|
|
- `opportunities-by-owner-close-window`
|
|
Use when the ask names one explicit territory owner or seller and you need opportunities in a close-date window.
|
|
- `opportunities-by-owner-manager-close-window`
|
|
Use when the ask names a manager of territory owners and you need opportunities in a close-date window.
|
|
- `workloads-by-owner-current`
|
|
Use for current-state workload asks for one explicit territory owner. It defaults to `current-quarter`, `Cloud Infrastructure - Workloads`, and `WORKLOAD`.
|
|
- `workloads-by-owner-manager-current`
|
|
Use for current-state workload asks for owners under one explicit manager-of-owner. It defaults to `current-quarter`, `Cloud Infrastructure - Workloads`, and `WORKLOAD`.
|
|
- `workloads-by-owner-close-window`
|
|
Use when the ask names one explicit territory owner or seller and asks for workloads in an explicit close-date window.
|
|
- `workloads-by-owner-manager-close-window`
|
|
Use when the ask names a manager of territory owners and asks for workloads in an explicit close-date window.
|
|
- `workloads-by-resource-close-window`
|
|
Use when the ask names one explicit allocated resource and asks for workload revenue lines in a close-date window.
|
|
- `workloads-by-manager-resource-close-window`
|
|
Use for org-wide workload revenue lines closing inside a direct date window when the ask is about opportunities that have allocated resources under one or more named managers. This intent gets manager/resource linkage only from `Knowledge DV - Presales Involvement Aux - V1`, gets commercial rows only from `Knowledge DV - Opportunities - V2`, filters on `Revenue Line Close Date`, and does not query `DV - SE Team` unless the user explicitly asks for SR details.
|
|
- `srs-by-resource`
|
|
Use for SRs by person with `--resource`.
|
|
|
|
### 2. Views
|
|
|
|
Use a view when the extract shape is already known.
|
|
|
|
- `opportunity-details`
|
|
- `sr-details`
|
|
- `opportunities-close-window`
|
|
- `srs-by-resource-email`
|
|
- `sa-attach-pipeline-details`
|
|
- `sa-attach-open-pipeline`
|
|
- `sa-attach-won-pipeline`
|
|
- `sa-attach-involvement-distribution`
|
|
- `sa-attach-hours-by-opportunity`
|
|
- `sa-attach-presales-coverage`
|
|
|
|
Read [references/script-catalog.md](references/script-catalog.md) for the full built-in script surface.
|
|
|
|
### 3. Query Mode
|
|
|
|
Use `--query` for general ad hoc retrieval when the ask can be expressed as aliases plus filters, grouping, and ordering.
|
|
|
|
- Prefer `--query` over `--sql` for most non-recurring asks.
|
|
- Use field aliases instead of raw Oracle expressions whenever possible.
|
|
- Let query mode infer the safest source from the selected aliases: commercial aliases go org-wide-first on XSA datasets, while SR/session aliases stay on `DV - SE Team`.
|
|
- Use `--scope my-team` only when the user explicitly asks for the executing user's current-team view on org-wide-capable sources.
|
|
|
|
### 4. Raw SQL
|
|
|
|
Use `--sql` only when `--query` cannot express the ask cleanly.
|
|
|
|
- Prefer placeholders such as `{{opportunityId}}`, `{{closeDate}}`, `{{bookingValue}}`, `{{workloadAmount}}`, `{{subjectArea}}`, and `{{securityEntryPointFilter}}`.
|
|
- Use `--render-sql` when you need to validate the final SQL locally without a backend call.
|
|
- If quoting becomes fragile in PowerShell, use `scripts/run-sales-intelligence-sql.mjs`.
|
|
|
|
## Authentication Workflow
|
|
|
|
1. Run `--check-auth` only when the session may be stale.
|
|
2. For normal fetch calls, if the saved session files are missing or the backend redirects to Oracle sign-in, `fetch-sales-intelligence.mjs` now opens the browser refresh flow automatically, waits for login, writes fresh session files, and retries the backend request.
|
|
3. Use `scripts/refresh-auth-state.mjs` manually only when you want to pre-refresh the browser session yourself or troubleshoot the automatic flow.
|
|
4. Use `scripts/refresh-auth-direct.mjs` when browser auth is unavailable or when you explicitly want the terminal-driven MFA flow.
|
|
5. `--check-auth` stays diagnostic-only and does not open the browser automatically.
|
|
|
|
## Data-Specific Rules
|
|
|
|
- For manager or hierarchy asks, start with [references/initial-context-catalog.md](references/initial-context-catalog.md) before touching the CLI catalog.
|
|
- For generic opportunity and pipeline asks, prefer `opportunities-default`.
|
|
- For close-date asks, prefer `opportunities-close-date`, `opportunities-close-month`, or `opportunities-close-window`.
|
|
- For fiscal-quarter asks, prefer `--quarter` with `FY26-Q4`, `Q4 FY26`, or `current-quarter`.
|
|
- For asks phrased as `week 1`..`week 53` or `w1`..`w53`, use the annual June-to-May week mapping in [references/script-catalog.md#week-reference](references/script-catalog.md#week-reference) and prefer `--week` plus optional `--week-year`.
|
|
- Treat wording like `agora`, `atual`, `mês corrente`, `quarter atual`, and `FY corrente` as current-period shortcuts whenever the matching flag supports it.
|
|
- For `opportunities-close-window`, close-window intents, and `sa-attach-*` commercial views, date-window flags now constrain `Revenue Line Close Date` directly, including `--week`, `--quarter`, and explicit `--from-date/--to-date`.
|
|
- For present-state workload asks about one seller or one seller-manager, prefer `workloads-by-owner-current` or `workloads-by-owner-manager-current`.
|
|
- For current-team coverage asks, prefer `opportunities-current-team-close-window`.
|
|
- Treat `país` or `country` wording as `--cluster` only when the user names a supported commercial cluster. Do not invent a separate `--country` flag.
|
|
- For seller or territory-owner opportunity asks with explicit dates, prefer `opportunities-by-owner-close-window`.
|
|
- For seller-manager opportunity asks with explicit dates, prefer `opportunities-by-owner-manager-close-window`.
|
|
- For resource workload asks with explicit dates, prefer `workloads-by-resource-close-window`.
|
|
- For territory-owner workload asks with explicit dates, prefer `workloads-by-owner-close-window`; keep `workloads-by-owner-current` for current-state or current-quarter asks.
|
|
- For territory-owner-manager workload asks with explicit dates, prefer `workloads-by-owner-manager-close-window`; keep `workloads-by-owner-manager-current` for current-state or current-quarter asks.
|
|
- For asks like `recursos do <manager de recurso> em pipe na week 2`, prefer `opportunities-by-manager-close-window --manager-email <manager de recurso> --week w2`.
|
|
- For asks like `workloads com close date nos proximos 7 dias em oportunidades com recursos abaixo de <manager de recurso 1> e <manager de recurso 2>`, prefer `workloads-by-manager-resource-close-window --manager-email-list <email do manager de recurso 1>,<email do manager de recurso 2> --from-date today --to-date +7d`.
|
|
- For that workload-by-manager-resource intent, treat `resourceEmails` as the org-wide allocated resource list from Presales Involvement Aux. The default result is involvement/allocation only; do not fetch SR details unless the user explicitly asks for SRs.
|
|
- When crossing SRs to workloads or opportunities, keep the `opportunityId` join as the confirmed linkage and also consider same-resource same-customer SRs without a usable `opportunityId` as internal-SR candidates. This is the current safe fallback because `Parent SR Number` is still not queryable through the logical SQL path.
|
|
- For SR resource lookups, default to SR Team Level `1..4` email matching and use `Lead Email` only for explicit leader intent.
|
|
- Accept short Oracle user ids through `--resource` when available.
|
|
- Use `--owner-email` for direct territory-owner filters and `--owner-manager-email` for owner-hierarchy filters on SA Attach workload reads.
|
|
- Use `--forecast-type` for natural-language asks such as `forecast`, `upside`, or `won` on SA Attach workload reads.
|
|
- Keep opportunity-linked monetary outputs consistent as `bookingValue` and `workloadAmount`.
|
|
- Treat `Knowledge DV - Opportunities - V2` as the normal source for pipeline, opportunity, won, close date, territory, owner, booking, and workload.
|
|
- Interpret user wording `vendedor`, `sales rep`, and `lider de vendas` as `territory owner` by default.
|
|
- Treat org-wide-capable XSA datasets as org-wide reads in `--scope auto`: `Knowledge DV - Opportunities - V2`, `Knowledge DV - Hours - V2`, `Knowledge DV - Presales Involvement Aux - V1`, and `Knowledge DV - Revn Lines by SE`.
|
|
- Treat `Knowledge DV - Hours - V2` as the normal source for hierarchy ownership and hours; default to org-wide unless the ask explicitly requests current-team scope.
|
|
- Treat `Knowledge DV - Presales Involvement Aux - V1` as the normal source for allocated resource, manager, and presales-coverage linkage; default to org-wide unless the ask explicitly requests current-team scope.
|
|
- Treat `Knowledge DV - Revn Lines by SE` as the normal source for detailed revenue-line extracts; default to org-wide unless the ask explicitly requests current-team scope.
|
|
- Treat `DV - SE Team` as self-scoped to the executing user, with hierarchy starting from that user and expanding only downward through their team.
|
|
- Treat `DV - SE Team` as fallback for commercial views only when the ask is explicitly about the current user's team, and as the normal source for session context and SR reads.
|
|
- When mixing org-wide commercial rows with current-team resource enrichment, preserve every org-wide opportunity/workload row and leave resource fields empty when there is no match.
|
|
- When a result mixes org-wide commercial rows with team-scoped resources, say that explicitly in the answer: `Opportunities/workloads: org-wide`, `Resources: only your current team`, and `rows without a match keep empty resource fields`.
|
|
- When a result includes any `scope.components`, prefer those component lines over a single simplified label because they identify which source is org-wide and which source is my-team-only.
|
|
|
|
## Inputs And Outputs
|
|
|
|
Input expectations:
|
|
|
|
- business ask phrased in natural language, or
|
|
- a known intent/view/query/SQL request, optionally with date, month, resource, manager, or status filters
|
|
|
|
Normal output contract from `fetch-sales-intelligence.mjs`:
|
|
|
|
- `request`
|
|
- `scope`
|
|
- `apiMetrics`
|
|
- `columns`
|
|
- `records`
|
|
- `summary` for derived intents when relevant
|
|
- `warnings`
|
|
- `raw` for backend debugging
|
|
|
|
User-facing answer contract:
|
|
|
|
- Every answer that reports DV data must include a short "Context / assumptions" note near the result. Do not leave scope, defaults, or implicit DV assumptions only in the JSON.
|
|
- Always state the effective scope as one of `org-wide`, `my-team-only`, or `mixed-consistent`. If `scope.components` exists, use it as the authoritative source-by-source disclosure instead of compressing the result into one label.
|
|
- Always state the main source and execution path used: `--intent`, `--view`, `--query`, or `--sql`; the source subject area when known; and whether `--scope auto`, `--scope org-wide`, or `--scope my-team` was used.
|
|
- When defaults are applied, explicitly say so. At minimum disclose these common defaults when relevant: `cluster = Brazil`; `--scope auto`; live Oracle DV session fiscal year; current-period shortcuts such as `current-quarter`, current FY, or the current June-to-May week cycle; default status filters; default `--limit`; and SA Attach defaults for solution, product LOB, revenue type group, sales credit type, and minimum opportunity probability.
|
|
- If the user did not specify geography and the selected SA Attach/commercial path applies the traced workbook filter `cluster = Brazil`, say `Cluster default: Brazil`. If geography was overridden or no cluster filter applies, say that instead.
|
|
- If date windows, weeks, quarters, or "current" wording were interpreted, state the resolved period and the date field being filtered. For commercial SA Attach close-window answers, say that the window filters `Revenue Line Close Date`.
|
|
- If user wording required role interpretation, state it briefly, for example `vendedor`/`sales rep`/`lider de vendas` interpreted as `territory owner`, or short Oracle uid normalized to `@oracle.com`.
|
|
- If SR, resource, manager, or workload enrichment involved implicit joins, state the join assumption: `opportunityId` is the confirmed linkage; same-resource same-customer SRs without usable `opportunityId` are only fallback candidates; and current-team enrichment can leave unmatched org-wide rows with empty resource fields.
|
|
- Always include API effort and data-shape caveats: `Raw rows pulled from the API: X`; whether the result hit the requested/default limit; any `warnings`; and whether displayed monetary fields use truncated `k` values while `raw` keeps backend-native values.
|
|
- Never describe the numbers as "all company", "all Brazil", or "complete pipeline" unless the disclosed `scope`, filters, defaults, and limits actually support that statement.
|
|
|
|
Scope disclosure rule:
|
|
|
|
- Use the emitted `scope` object when wording the answer.
|
|
- `scope.scopeMode = org-wide` means the visible rows are org-wide.
|
|
- `scope.scopeMode = my-team-only` means the visible rows are limited to the executing user's current team.
|
|
- `scope.scopeMode = mixed-consistent` means the opportunity/workload rows remain org-wide, resource enrichment is team-scoped, and unmatched rows stay in the output with empty resource fields.
|
|
- `scope.components` is the most precise source-by-source disclosure. Use it when present, especially for mixed answers.
|
|
- For `workloads-by-manager-resource-close-window`, `scope.scopeMode = org-wide` means both workload rows and manager/resource allocation came from org-wide Knowledge DV sources. If the user explicitly asks for SR details, disclose the separate SR lookup as `DV - SE Team` / my-team-only.
|
|
- Explain in the output to the user which context was used to retrieve the information.
|
|
|
|
API effort disclosure rule:
|
|
|
|
- Use `apiMetrics.totalRowsPulledFromApi` as the canonical count of raw rows returned by Oracle DV for that invocation.
|
|
- Do not replace that number with final `records.length`; they mean different things.
|
|
- Do not add local-cache-only rows to this number. If the skill reused local fiscal-year/session metadata, those local reads do not count toward `apiMetrics.totalRowsPulledFromApi`.
|
|
- Prefer wording the answer with a sentence like `Raw rows pulled from the API: X.`
|
|
|
|
Display-format rule:
|
|
|
|
- `bookingValue` and `workloadAmount`, plus `summary.totalBookingValue` and `summary.totalWorkloadAmount`, are emitted as truncated thousands with a `k` suffix, for example `849k`. The `raw` section keeps the backend-native values.
|
|
|
|
Read [references/script-catalog.md](references/script-catalog.md) for the full CLI contract and [references/api-map.md](references/api-map.md) for traced backend details.
|
|
|
|
## Minimal Commands
|
|
|
|
Codex normally invokes this skill from the current agent workspace, so the default runtime is `./knowledge-one-view-cli/runtime/`. If you run the scripts manually from the installed skill directory or any other location, pass `--runtime-home` or set `ORACLE_SI_RUNTIME_HOME` to point back to the target workspace.
|
|
|
|
For the consolidated technical guide, testing strategy, and workspace artifact layout, read [docs/docs.html](docs/docs.html). Test definitions stay inside the installed skill `tests/` folder, while test-run artifacts go to the workspace-side `knowledge-one-view-cli/output/` and `knowledge-one-view-cli/tmp/` folders.
|
|
|
|
Check auth:
|
|
|
|
```powershell
|
|
node .\scripts\fetch-sales-intelligence.mjs `
|
|
--check-auth
|
|
```
|
|
|
|
Generic pipeline or opportunities:
|
|
|
|
```powershell
|
|
node .\scripts\fetch-sales-intelligence.mjs `
|
|
--intent opportunities-default `
|
|
--limit 200
|
|
```
|
|
|
|
Exact close date:
|
|
|
|
```powershell
|
|
node .\scripts\fetch-sales-intelligence.mjs `
|
|
--intent opportunities-close-date `
|
|
--date 2026-05-02
|
|
```
|
|
|
|
Calendar month:
|
|
|
|
```powershell
|
|
node .\scripts\fetch-sales-intelligence.mjs `
|
|
--intent opportunities-close-month `
|
|
--month 2026-04
|
|
```
|
|
|
|
Annual week shortcut:
|
|
|
|
```powershell
|
|
node .\scripts\fetch-sales-intelligence.mjs `
|
|
--intent opportunities-by-manager-close-window `
|
|
--manager-email <email do manager de recurso> `
|
|
--week w2 `
|
|
--week-year 2026
|
|
```
|
|
|
|
Current workload by owner:
|
|
|
|
```powershell
|
|
node .\scripts\fetch-sales-intelligence.mjs `
|
|
--intent workloads-by-owner-current `
|
|
--owner-email <email do vendedor> `
|
|
--forecast-type Forecast,Upside
|
|
```
|
|
|
|
Current workload by owner manager:
|
|
|
|
```powershell
|
|
node .\scripts\fetch-sales-intelligence.mjs `
|
|
--intent workloads-by-owner-manager-current `
|
|
--owner-manager-email <email do manager do vendedor> `
|
|
--quarter current-quarter `
|
|
--forecast-type Forecast
|
|
```
|
|
|
|
Org-wide workload close window by manager/resource:
|
|
|
|
```powershell
|
|
node .\scripts\fetch-sales-intelligence.mjs `
|
|
--intent workloads-by-manager-resource-close-window `
|
|
--manager-email-list <email do manager de recurso 1>,<email do manager de recurso 2> `
|
|
--from-date today `
|
|
--to-date +7d
|
|
```
|
|
|
|
SRs by person:
|
|
|
|
```powershell
|
|
node .\scripts\fetch-sales-intelligence.mjs `
|
|
--intent srs-by-resource `
|
|
--resource <recurso>
|
|
```
|
|
|
|
Alias-based ad hoc query:
|
|
|
|
```powershell
|
|
node .\scripts\fetch-sales-intelligence.mjs `
|
|
--query `
|
|
--select opportunityId,opportunityName,closeDate,bookingValue,workloadAmount `
|
|
--where "closeDate = DATE '2026-05-02'"
|
|
```
|