marceloarbore/knowledge-one-view-cli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0d57f947573fd1f77f21677514213133ec93f3ca
knowledge-one-view-cli/references/api-map.md

515 lines
19 KiB
Markdown
Raw Blame History

# 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`
Reference in New Issue View Git Blame Copy Permalink