# Knowledge-One-View-CLI API Map

Read this file when Oracle DV behavior changes, a workbook tab must be retraced, or you need traced endpoint and default-filter details that are too low-level for the main skill guide.

## Quick Navigation

- Workbook identity: [Traced Workbook](#traced-workbook)
- Required auth/session state: [Required Session Inputs](#required-session-inputs)
- Direct and fallback endpoints: [Traced Endpoints](#traced-endpoints)
- Local metadata and field shortcuts: [Fast Local Metadata](#fast-local-metadata)
- Common query patterns: [Fast Query Patterns](#fast-query-patterns)
- Traced workbook-tab defaults: [Traced Tab Defaults](#traced-tab-defaults)

## Traced Workbook

- Workbook URL:
  `https://salesintelligence-dv.oracle.com/ui/dv/ui/project.jsp?pageid=visualAnalyzer&reportmode=presentation&reportpath=%2F%40Catalog%2Fshared%2FTeam%20Sharing%20Area%2FLAD%2FLAD%20Sales%20Operations%2FLAD%20Production%2FLAD%20Knowledge%20One%20View`
- Platform:
  Oracle Analytics / Oracle DV
- Primary commercial subject area:
  `XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')`

Keep the `ANNA.DE.MAURO@ORACLE.COM` token exactly as traced in XSA dataset references. It is part of the logical dataset identifier, not a disposable example.

## Required Session Inputs

The direct API calls worked with:

- Cookies from Playwright `storageState`
- `authorization: session`
- `x-csrf-token`
- `x-bitech-clientbin`
- `x-requested-with: XMLHttpRequest`
- Workbook `referer`

`x-bitech-clientbin` also appears in the workbook bootstrap HTML inside static asset paths such as:

`/static/dv/oracle-jet-bundles/18.1.2.fd48e9d8895d/...`

The refresh helper writes both the cookies and these request headers to disk:

- `auth-state.json`
- `session-meta.json`

The fetch script also persists refreshed cookies plus updated CSRF/clientbin metadata back to those files after a session restore so later runs reuse the corrected backend state.
When the saved files are missing or Oracle redirects a normal fetch call back to sign-in, the fetch script can now invoke the browser refresh helper automatically, then reload the session artifacts and retry the backend request.
That makes the runtime/session path parameters operationally important, not just convenience flags.

## Traced Endpoints

### Preferred Direct Endpoint

- `POST /ui/dv/ui/api/v1/sqlquery/execute`
  Use for custom Oracle logical SQL and for the reusable `opportunity-details` and `sr-details` views in this skill.
  Body shape:

```json
{
  "aQueryInfos": [
    {
      "sQuery": "SELECT valueof(RV_CURR_FISCAL_YEAR) FROM \"DV - SE Team\"",
      "nResultsLimit": 1
    }
  ],
  "bUseCache": true
}
```

  Response shape:

```json
{
  "aQueriesResults": [
    {
      "eStatus": "FINISHED",
      "aColumnTypes": ["varchar"],
      "aResults": [["FY26"]]
    }
  ]
}
```

### Metadata / Bootstrap Endpoints

- `POST /ui/dv/ui/api/v1/modelmetadata/reportdatasetsmetadatajson`
  Traced from `Data Quality`. Useful when Oracle changes dataset metadata or a new workbook view must be reconstructed.
- `POST /ui/dv/ui/api/v1/infer/activities`
  Telemetry only. Ignore for data retrieval.
- `GET /ui/dv/ui/api/v3/items-content`
  Static workbook assets such as images. Ignore for data retrieval.

### Workbook Rendering Endpoints

- `POST /ui/dv/ui/api/v2/data/executeOrPoll`
- `POST /ui/dv/ui/api/v2/data/poll`

These drive the rendered workbook tabs. They are useful as fallback references because the POST payloads contain the exact traced columns and default filters, but they are noisier than `sqlquery/execute`.

## Fast Local Metadata

The skill now keeps a local field catalog inside `scripts/fetch-sales-intelligence.mjs` for the most common logical fields, so repeated asks do not need rediscovery. Use:

- `--catalog`
- `--list-intents`
- `--describe-intent srs-by-resource`
- `--list-fields`
- `--list-fields --entity Opportunity`
- `--list-fields --role filter`
- `--describe-field closeDate`

Use the intent shortcuts first for the recurring asks that previously caused parameter guesswork:

- `opportunities-close-date`
  Uses `--date`
- `opportunities-close-month`
  Uses `--month`
- `srs-by-resource`
  Uses `--resource`

For ad hoc SQL, prefer template placeholders over raw Oracle expressions:

- `{{opportunityId}}`
- `{{closeDate}}`
- `{{bookingValue}}`
- `{{workloadAmount}}`
- `{{subjectArea}}`
- `{{securityEntryPointFilter}}`

Render those placeholders locally without a backend call:

```powershell
node .\scripts\fetch-sales-intelligence.mjs `
  --render-sql `
  --sql "SELECT {{opportunityId}}, {{closeDate}} FROM {{subjectArea}} WHERE {{securityEntryPointFilter}}"
```

For most ad hoc retrieval, prefer declarative query mode over raw SQL:

```powershell
node .\scripts\fetch-sales-intelligence.mjs `
  --query `
  --select opportunityId,opportunityName,closeDate,bookingValue,workloadAmount `
  --where "closeDate = DATE '2026-05-02'"
```

Query mode infers the safest source from the selected aliases. Commercial opportunity, revenue-line, hours, and presales-coverage aliases use org-wide-capable XSA sources in `--scope auto`; SR and session aliases remain on `DV - SE Team`, which is my-team-only.

Important known fields:

- `closeDate`
  `"Opportunity"."Close Date"`
  Use direct date literals: `DATE '2026-03-27'`
- `opportunityId`
  `"Opportunity"."Opportunity ID"`
- `opportunityName`
  `"Opportunity"."Opportunity Name"`
- `opportunityStatus`
  `"Opportunity"."Status"`
- `customerName`
  `"Customer"."Customer Name"`
- `salesStage`
  `"Opportunity"."Sales Stage"`
- `opportunityValue`
  `"Opportunity"."Opportunity Value"`
- `bookingValue`
  `"Opportunity"."Opportunity Value"`
  Preferred alias when the intent is to compare booking against `workloadAmount`.
- `workloadAmount`
  `"Opportunity"."Workload Amount"`
- `optyCloseFiscalYear`
  `"Time (Close Date Opportunity)"."Opty Close Fiscal Year"`
- `srNumber`
  `"Service Request"."SR Number"`
- `srStatus`
  `"Service Request"."Status"`
- `srTeamLevel1EmailAddress`
  `"SR Team"."SE Team Level 1 Email Address"`
- `srTeamLevel2EmailAddress`
  `"SR Team"."SE Team Level 2 Email Address"`
- `srTeamLevel3EmailAddress`
  `"SR Team"."SE Team Level 3 Email Address"`
- `srTeamLevel4EmailAddress`
  `"SR Team"."SE Team Level 4 Email Address"`
- `leadEmail`
  `"Service Request"."Lead Email"`
  Use only when the intent is explicitly to query the SR leader.

## Fast Query Patterns

### Ad Hoc SQL Without Oracle Expression Guesswork

Use the local placeholder expansion:

```powershell
node .\scripts\fetch-sales-intelligence.mjs `
  --sql "SELECT {{opportunityId}}, {{opportunityName}}, {{closeDate}}, {{bookingValue}}, {{workloadAmount}} FROM {{subjectArea}} WHERE {{securityEntryPointFilter}} AND {{closeDate}} = DATE '2026-05-02'"
```

The script expands that locally to Oracle logical SQL before execution.
When the `SELECT` list is simple enough, the script also infers output column names and returns object-shaped `records` instead of only raw row arrays. Explicit `AS` aliases are respected.

### Declarative Query Mode

Use query mode when the ask is naturally "fields + filter + grouping + ordering":

```powershell
node .\scripts\fetch-sales-intelligence.mjs `
  --query `
  --select opportunityId `
  --measure sum:bookingValue:totalBooking,sum:workloadAmount:totalWorkload `
  --where "closeDate = DATE '2026-05-02'" `
  --group-by opportunityId `
  --order-by totalBooking:desc
```

Query mode reduces guesswork by:

- inferring the configured source automatically from the selected aliases
- using org-wide XSA sources first for commercial aliases in `--scope auto`
- injecting the standard team-security filter only when the selected source requires it or when `--scope my-team` is explicitly requested on an org-wide-capable source
- accepting field aliases directly inside `--select` and `--where`
- supporting aggregate specs like `sum:bookingValue:totalBooking`
- returning object-shaped records with stable output columns

### Backend Scope Reality

Use this when deciding whether a request can be answered org-wide or must be disclosed as current-team only:

- `Knowledge DV - Opportunities - V2`, `Knowledge DV - Hours - V2`, `Knowledge DV - Presales Involvement Aux - V1`, and `Knowledge DV - Revn Lines by SE` are treated as org-wide-capable XSA datasets by the skill. In `--scope auto`, the script avoids the current-team security predicate unless the chosen view or intent explicitly needs it.
- `--scope my-team` on an org-wide-capable source intentionally adds the current-team predicate so the same dataset can be used for a narrower current-team read.
- `DV - SE Team` is effectively my-team-only for this skill. Use it for SRs, session context, and fields that have no org-wide source. Do not use it as a generic org-wide commercial fallback.
- For mixed outputs, prefer `scope.components` and `scope.disclosureLines` over a single label because one component may be org-wide while another remains my-team-only.

### Opportunities By Close-Date Window

Use the built-in intent or built-in view instead of rewriting SQL:

Exact 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
```

Explicit window:

```powershell
node .\scripts\fetch-sales-intelligence.mjs `
  --view opportunities-close-window `
  --from-date today `
  --to-date +7d
```

Primary logical SQL pattern:

```sql
SELECT
  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity ID",
  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity Name",
  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Customer Name (Original)",
  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity Status",
  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Close Date",
  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Sales Stage",
  MAX(XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Pipeline") AS bookingValue,
  MAX(XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Pipeline") AS workloadAmount
FROM XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')
WHERE XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Close Date" >= DATE '2026-03-27'
  AND XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Close Date" <= DATE '2026-04-03'
GROUP BY
  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity ID",
  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity Name",
  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Customer Name (Original)",
  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Opportunity Status",
  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Close Date",
  XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')."Columns"."Sales Stage"
ORDER BY 5, 1
```

Fallback behavior:

- if the ask is explicitly about the current user's team and the primary XSA query fails, the skill may rerun the commercial read against `DV - SE Team`
- generic org-wide commercial reads stay on `Knowledge DV - Opportunities - V2` and do not fall back to `DV - SE Team`

In the built-in `opportunities-close-window` view, the last two fields are returned from the org-wide XSA `Pipeline` column:

- `bookingValue` -> `Knowledge DV - Opportunities - V2` / `"Columns"."Pipeline"`
- `workloadAmount` -> `Knowledge DV - Opportunities - V2` / `"Columns"."Pipeline"`

The `bookingValue` and `workloadAmount` names are preserved for user-facing compatibility with opportunity and workload reports. For org-wide query-mode reads from `Knowledge DV - Opportunities - V2`, prefer the same `Pipeline` backing field because direct row-level reads of `"Opportunity Value"` and `"Workload Amount"` can fail in Oracle DV.

### SRs By Resource Email

Use the built-in intent or built-in view instead of writing custom SQL:

Shortest path:

```powershell
node .\scripts\fetch-sales-intelligence.mjs `
  --intent srs-by-resource `
  --resource resource.member
```

Equivalent direct view call:

```powershell
node .\scripts\fetch-sales-intelligence.mjs `
  --view srs-by-resource-email `
  --resource resource.member
```

Default matching rule:

```sql
(
  "SR Team"."SE Team Level 1 Email Address" = 'resource.member@oracle.com'
  OR "SR Team"."SE Team Level 2 Email Address" = 'resource.member@oracle.com'
  OR "SR Team"."SE Team Level 3 Email Address" = 'resource.member@oracle.com'
  OR "SR Team"."SE Team Level 4 Email Address" = 'resource.member@oracle.com'
)
```

Only use lead matching when the ask is explicitly about the leader:

```powershell
node .\scripts\fetch-sales-intelligence.mjs `
  --view srs-by-resource-email `
  --resource-email resource.member@oracle.com `
  --match-role lead
```

The built-in `srs-by-resource-email` view also returns:

- `bookingValue` -> `"Opportunity"."Opportunity Value"`
- `workloadAmount` -> `"Opportunity"."Workload Amount"`

The CLI now normalizes Oracle date strings in built-in output, so values such as `02-MAY-26` are returned as `2026-05-02`.

## Traced Tab Defaults

### Opportunity Details

- Current canvas:
  `canvas!4`
- Plugin:
  `oracle.bi.tech.table`
- Default filters:
  - `Security.Entry Point in VALUEOF(NQ_SESSION."SEC_ARIA_SI-SR-TEAM")`
  - `Opty Close Fiscal Year = current FY`
  - `Opportunity Status in (Open, Won, Won Pending)`
  - `SE Team Active Flag = Y`
  - `SE Team Manager Flag = N`
  - `SR Source = Opportunity`
- Important columns:
  - `Opportunity ID`
  - `# Opportunity Hours`
  - `Status`
  - `Workload Amount`
  - `Registry ID`
  - `Customer Name`
  - `Deal Qualification`
  - `Forecast Type Group`
  - `Opportunity Value`
  - `Current FY Opp Hours`
  - `Total Opportunity Hours`
  - `Opty Close Fiscal Quarter`
  - `# SEs With Effort`
  - `# Service Requests with Effort`
  - `Country`
  - `Sales Stage`
  - `Revenue Type Group`
  - `LOB Type`
  - `All Products`
  - `Opportunity Name`
  - `All Workloads`
  - `Covered Flag`
  - `All Implementers`
  - `Win Probability`

### SR Details

- Current canvas:
  `canvas!5`
- Plugin:
  `oracle.bi.tech.table`
- Default filters:
  - `Security.Entry Point in VALUEOF(NQ_SESSION."SEC_ARIA_SI-SR-TEAM")`
  - `Opty Close Fiscal Year = current FY`
  - `Opportunity Status = Open`
  - `SE Team Active Flag = Y`
  - `SE Team Manager Flag = N`
- Important columns:
  - `SR Number`
  - `Parent SR Number`
  - `Service Request Status`
  - `Title`
  - `Queue Name`
  - `Country`
  - `Registry ID`
  - `Customer Name`
  - `SR Source`
  - `Opportunity ID`
  - `Opportunity Name`
  - `Opportunity Status`
  - `Win Probability`
  - `Primary Pillar`
  - `Opportunity Value`
  - `Workload Amount`
  - `Total SR Hours`
  - `Lead Email`
  - `SR Requester Email Address`
  - `Create SR Day`
  - `Close SR Day`
  - `Customer Deadline`
  - `Internal Deadline`
  - `Last Effort`
  - `# Service Requests with Effort`
  - `# SEs With Effort`
  - `# Hours (Excl. Time Off)`
  - `Service Description`

Current limitation:

- `Parent SR Number` is visible in traced workbook metadata, but the direct logical SQL path used by the CLI still fails when selecting it explicitly.
- Because of that, current internal-SR reconciliation in the skill uses a safe fallback: confirmed joins stay based on `Opportunity ID`, and additional internal-SR candidates are inferred only when the same resource has SRs for the same customer without a usable `Opportunity ID`.

### Data Quality

The `Data Quality` tab used:

- `POST /ui/dv/ui/api/v1/sqlquery/execute`
- `POST /ui/dv/ui/api/v1/modelmetadata/reportdatasetsmetadatajson`

That trace confirms the workbook can be queried directly through Oracle logical SQL without rendering the visualization.

### Commercial Opportunity Datasets

- Current canvas:
  `canvas!15`
- Traced endpoints:
  - `POST /ui/dv/ui/api/v2/data/executeOrPoll`
  - `POST /ui/dv/ui/api/v2/modelmetadata/subjectareas`
  - `POST /ui/dv/ui/api/v2/metadata/interactionpaths`
  - `POST /ui/dv/ui/api/v1/dataset/datasets/metadata`
  - `POST /ui/dv/ui/api/v1/modelmetadata/reportdatasetsmetadatajson`
- Traced workbook sources:
  - `XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Opportunities - V2')`
  - `XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Hours - V2')`
  - `XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Presales Involvement Aux - V1')`
  - `XSA('ANNA.DE.MAURO@ORACLE.COM'.'Knowledge DV - Revn Lines by SE')`
- Observed metadata lookup:
  - `XSA('ANNA.DE.MAURO@ORACLE.COM'.'One View Tech - Usage Information')`

The first traced SA Attach visuals used `Knowledge DV - Opportunities - V2` as the active subject area and exposed these traced defaults:

- Recommended default for generic opportunity retrieval:
  `--intent opportunities-default`
- `Cluster = Brazil`
- `Solution in ('Cloud Infrastructure - Workloads', 'Hardware - Bookings', 'On-Premise Technology - Bookings')`
- `Sales Credit Type = QUOTA`
- `Executive Product LOB in ('Cloud Infrastructure', 'Hardware', 'License')`
- `Revenue Type Group in ('NEW', 'EXPANSION', 'WORKLOAD')`
- Current skill default: `Opportunity Probability >= 0`
- Older workbook traces sometimes showed `Opportunity Probability >= 40`
- `Revenue Line Status = Open` for the open-pipeline visuals
- `Revenue Line Status in ('Won', 'Won Pending')` for the won-pipeline visual
- Open rows are allowed in any close year, while won rows are constrained to previous/current fiscal year
- Compatibility note:
  older traces may still mention `License and Hardware` or `WORKLOADS`; the skill now normalizes those aliases to the backend values `License` + `Hardware` and `WORKLOAD`.

Traced view mappings:

- `view!1597`
  `oracle.bi.tech.ngperformancetile`
  Open pipeline tile based on `SUM(Pipeline)` from `Knowledge DV - Opportunities - V2`
- `view!1612`
  `oracle.bi.tech.ngperformancetile`
  Won pipeline tile based on `SUM(Pipeline)` from `Knowledge DV - Opportunities - V2`
- `view!1602`
  `oracle.bi.tech.chart.stackbar100`
  Involvement distribution chart based on `Pipeline`, `Revenue Line Probability`, `Presales Involvement Flag`, and `Opportunity Hours Attribute`

The traced involvement bucket logic is:

```sql
CASE
  WHEN SUM(
    CASE WHEN <current-team filter on Presales Involvement Aux - V1>
      THEN "Opportunity Hours Attribute"
    END BY "Opportunity ID"
  ) > 0
    THEN '1. My Team Involvement'
  WHEN "Presales Involvement Flag" = 'Y'
    THEN '2. Other Presales Involvement'
  ELSE '3. No Presales Involvement'
END
```

Current skill coverage now maps that tab through these direct views:

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