Files

Marcelo Arbore 8662a153fe Primeiro Commit v0.beta1

2026-04-29 00:27:50 -03:00

19 KiB

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.

Workbook identity: Traced Workbook
Required auth/session state: Required Session Inputs
Direct and fallback endpoints: Traced Endpoints
Local metadata and field shortcuts: Fast Local Metadata
Common query patterns: Fast Query Patterns
Traced workbook-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:

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

Response shape:

{
  "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:

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:

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:

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":

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:

node .\scripts\fetch-sales-intelligence.mjs `
  --intent opportunities-close-date `
  --date 2026-05-02

Calendar month:

node .\scripts\fetch-sales-intelligence.mjs `
  --intent opportunities-close-month `
  --month 2026-04

Explicit window:

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

Primary logical SQL pattern:

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:

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

Equivalent direct view call:

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

Default matching rule:

(
  "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:

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:

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

19 KiB Raw Blame History