Skip to content

Commit 55c81c3

Browse files
claveryclavery
authored
feat: add CIP analytics topic, SDK client, and report tooling (#155)
* cip wip * docs * updated docs, sdc, etc * docs: clarify cip query token behavior placement * fix(cli): handle heredoc stdin input for cip query * fix(cli): buffer stdin for cip query --stdin * refactor(cli): use implicit stdin for cip query input * feat(cip): add metadata tables and describe commands * docs(skill): add linked CIP known tables reference * docs(skill): remove local filesystem path from CIP references * docs(skill): add CIP starter query reference pack
1 parent f12984e commit 55c81c3

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+4697
-208
lines changed

‎.changeset/add-cip-topic-and-reports.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
'@salesforce/b2c-cli': minor
3+
'@salesforce/b2c-tooling-sdk': minor
4+
---
5+
6+
Add a new `cip` command topic for Commerce Intelligence platform (CCAC - Commerce Cloud Analytics) with `cip query` for raw SQL and curated `cip report <report-name>` subcommands for analytics workflows, including CIP host override support and tenant-based CIP instance targeting.

‎docs/.vitepress/config.mts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ const guideSidebar = [
4949
items: [
5050
{text: 'Authentication Setup', link: '/guide/authentication'},
5151
{text: 'Account Manager', link: '/guide/account-manager'},
52+
{text: 'Analytics Reports (CIP/CCAC)', link: '/guide/analytics-reports-cip-ccac'},
5253
{text: 'IDE Integration', link: '/guide/ide-integration'},
5354
{text: 'Scaffolding', link: '/guide/scaffolding'},
5455
{text: 'Security', link: '/guide/security'},
@@ -68,6 +69,7 @@ const guideSidebar = [
6869
{text: 'Overview', link: '/cli/'},
6970
{text: 'Code Commands', link: '/cli/code'},
7071
{text: 'Content Commands', link: '/cli/content'},
72+
{text: 'CIP Commands', link: '/cli/cip'},
7173
{text: 'Job Commands', link: '/cli/jobs'},
7274
{text: 'Logs Commands', link: '/cli/logs'},
7375
{text: 'Sites Commands', link: '/cli/sites'},

‎docs/api-readme.md‎

Lines changed: 125 additions & 100 deletions
Large diffs are not rendered by default.

‎docs/cli/cip.md‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
---
2+
description: Run raw SQL and curated analytics reports against Commerce Intelligence Platform (CIP).
3+
---
4+
5+
# CIP Commands
6+
7+
Use `b2c cip` to query Commerce Intelligence Platform (CIP/CCAC) analytics data.
8+
9+
::: tip Production and Non-Production Hosts
10+
By default, CIP uses the production analytics host for tenants ending in `_prd` and the staging analytics host for other tenant IDs. Use `--staging` to force the staging host, or `--cip-host` for an explicit override.
11+
:::
12+
13+
## Command Overview
14+
15+
| Command | Description |
16+
| --------------------------------- | ---------------------------------------------- |
17+
| `b2c cip tables` | List tables from the CIP metadata catalog |
18+
| `b2c cip describe <table>` | Describe columns for a CIP table |
19+
| `b2c cip query` | Run raw SQL (argument, file, or stdin) |
20+
| `b2c cip report` | Report topic help and report command discovery |
21+
| `b2c cip report <report-command>` | Run a curated report command |
22+
23+
::: warning Availability
24+
These commands target Commerce Cloud Analytics (CCAC) data and are primarily used with production analytics tenants. Non-production access is available when Reports & Dashboards data tracking is enabled for supported 26.1+ environments.
25+
:::
26+
27+
## Authentication
28+
29+
CIP commands use **OAuth client credentials only**.
30+
31+
| Requirement | How to provide |
32+
| --------------------- | ---------------------------------------------- |
33+
| Client ID | `--client-id` or `SFCC_CLIENT_ID` |
34+
| Client Secret | `--client-secret` or `SFCC_CLIENT_SECRET` |
35+
| Tenant (CIP instance) | `--tenant-id` / `--tenant` or `SFCC_TENANT_ID` |
36+
37+
Your API client must include the **Salesforce Commerce API** role with a tenant filter that includes your target instance.
38+
39+
## Connection and Output Flags
40+
41+
These flags are available on all CIP commands:
42+
43+
| Flag | Description | Default |
44+
| -------------- | ------------------------------------- | --------------------------------------------- |
45+
| `--format` | Output format: `table`, `csv`, `json` | `table` |
46+
| `--fetch-size` | Frame fetch size for paging | `1000` |
47+
| `--cip-host` | CIP host override | `jdbc.analytics.commercecloud.salesforce.com` |
48+
| `--staging` | Use staging analytics host | `false` |
49+
50+
## Query and Report Date Flags
51+
52+
These flags are available on `cip query` and `cip report <report-command>` commands:
53+
54+
| Flag | Description | Default |
55+
| -------- | --------------------------------- | -------------------------- |
56+
| `--from` | Inclusive start date (YYYY-MM-DD) | First day of current month |
57+
| `--to` | Inclusive end date (YYYY-MM-DD) | Today |
58+
59+
## b2c cip tables
60+
61+
List tables from the CIP metadata catalog.
62+
63+
### Usage
64+
65+
```bash
66+
b2c cip tables [flags]
67+
```
68+
69+
### Flags
70+
71+
| Flag | Description |
72+
| ----------- | ---------------------------------------------------- |
73+
| `--schema` | Metadata schema to inspect (default: `warehouse`) |
74+
| `--pattern` | Table name pattern using SQL `LIKE` semantics |
75+
| `--all` | Include all table types (default filters to `TABLE`) |
76+
77+
### Examples
78+
79+
```bash
80+
# List warehouse tables
81+
b2c cip tables --tenant-id zzxy_prd --client-id <client-id> --client-secret <client-secret>
82+
83+
# Filter by table prefix
84+
b2c cip tables --tenant-id zzxy_prd --pattern "ccdw_aggr_%" --client-id <client-id> --client-secret <client-secret>
85+
86+
# Include metadata/system tables
87+
b2c cip tables --tenant-id zzxy_prd --schema metadata --all --client-id <client-id> --client-secret <client-secret>
88+
```
89+
90+
## b2c cip describe
91+
92+
Describe table columns using CIP metadata catalog.
93+
94+
### Usage
95+
96+
```bash
97+
b2c cip describe <table> [flags]
98+
```
99+
100+
### Flags
101+
102+
| Flag | Description |
103+
| ---------- | ----------------------------------------------------------- |
104+
| `--schema` | Metadata schema containing the table (default: `warehouse`) |
105+
106+
### Examples
107+
108+
```bash
109+
# Describe a warehouse table
110+
b2c cip describe ccdw_aggr_ocapi_request --tenant-id zzxy_prd --client-id <client-id> --client-secret <client-secret>
111+
112+
# Describe metadata system table
113+
b2c cip describe COLUMNS --schema metadata --tenant-id zzxy_prd --client-id <client-id> --client-secret <client-secret>
114+
```
115+
116+
## b2c cip query
117+
118+
Run raw SQL directly against CIP.
119+
120+
### Usage
121+
122+
```bash
123+
b2c cip query [SQL] [flags]
124+
```
125+
126+
### SQL Input Sources
127+
128+
Provide SQL from exactly one source:
129+
130+
1. Positional argument (`b2c cip query "SELECT ..."`)
131+
2. `--file <path>`
132+
3. Piped stdin (for example `cat query.sql | b2c cip query ...`)
133+
134+
### Query-Specific Flags
135+
136+
| Flag | Description |
137+
| -------------- | ------------------------ |
138+
| `--file`, `-f` | Read SQL query from file |
139+
140+
### Placeholders
141+
142+
`cip query` supports placeholder substitution:
143+
144+
- `<FROM>` is replaced by `--from`
145+
- `<TO>` is replaced by `--to`
146+
147+
### Examples
148+
149+
```bash
150+
# Inline SQL argument
151+
b2c cip query \
152+
--tenant-id zzxy_prd \
153+
--client-id <client-id> \
154+
--client-secret <client-secret> \
155+
"SELECT submit_date, num_orders FROM ccdw_aggr_sales_summary LIMIT 10"
156+
157+
# Non-production / staging analytics host
158+
b2c cip query \
159+
--tenant-id zzxy_stg \
160+
--staging \
161+
--client-id <client-id> \
162+
--client-secret <client-secret> \
163+
"SELECT submit_date, num_orders FROM ccdw_aggr_sales_summary LIMIT 10"
164+
165+
# Read SQL from file
166+
b2c cip query --file ./query.sql --tenant-id zzxy_prd --client-id <client-id> --client-secret <client-secret>
167+
168+
# Read SQL from stdin
169+
cat ./query.sql | b2c cip query --tenant-id zzxy_prd --client-id <client-id> --client-secret <client-secret>
170+
```
171+
172+
## b2c cip report
173+
174+
Run curated reports using dedicated subcommands.
175+
176+
### Usage
177+
178+
```bash
179+
b2c cip report --help
180+
b2c cip report <report-command> [flags]
181+
```
182+
183+
### Shared Report Flags
184+
185+
| Flag | Description |
186+
| ------------ | ------------------------------------------- |
187+
| `--describe` | Show report metadata and parameter contract |
188+
| `--sql` | Print generated SQL and exit |
189+
190+
Use `--sql` to pipe into `cip query`:
191+
192+
```bash
193+
b2c cip report sales-analytics --site-id Sites-RefArch-Site --sql \
194+
| b2c cip query --tenant-id zzxy_prd --client-id <client-id> --client-secret <client-secret>
195+
```
196+
197+
### Report Commands
198+
199+
| Command | Description | Extra Flags |
200+
| ------------------------------ | ------------------------------------- | ---------------------------- |
201+
| `sales-analytics` | Daily sales performance with AOV/AOS | `--site-id` |
202+
| `sales-summary` | Detailed sales records | `--site-id` (optional) |
203+
| `ocapi-requests` | OCAPI request volume and latency | `--site-id` |
204+
| `top-selling-products` | Top products by units/revenue | `--site-id` |
205+
| `product-co-purchase-analysis` | Frequently co-purchased products | `--site-id` |
206+
| `promotion-discount-analysis` | Promotion discount impact | none |
207+
| `search-query-performance` | Search revenue and conversion metrics | `--site-id`, `--has-results` |
208+
| `payment-method-performance` | Payment method adoption/performance | `--site-id` |
209+
| `customer-registration-trends` | Registration trends by date/device | `--site-id` |
210+
| `top-referrers` | Referrer traffic share | `--site-id`, `--limit` |
211+
212+
### Site ID Format
213+
214+
For report commands that accept `--site-id`, the common CIP format is:
215+
216+
`Sites-{siteId}-Site`
217+
218+
If your value does not match this pattern, the command warns and still uses your provided value.
219+
220+
### Examples
221+
222+
```bash
223+
# Run a report
224+
b2c cip report sales-analytics \
225+
--site-id Sites-RefArch-Site \
226+
--from 2025-01-01 \
227+
--to 2025-01-31 \
228+
--tenant-id zzxy_prd \
229+
--client-id <client-id> \
230+
--client-secret <client-secret>
231+
232+
# Show report parameter contract
233+
b2c cip report top-referrers --describe
234+
235+
# Generate SQL only
236+
b2c cip report top-referrers --site-id Sites-RefArch-Site --limit 25 --sql
237+
```
238+
239+
## Output Formats
240+
241+
Both `cip query` and report commands support:
242+
243+
- `--format table` (default)
244+
- `--format csv` (writes CSV to stdout)
245+
- `--format json` (writes JSON to stdout)
246+
- `--json` (global JSON mode)

‎docs/cli/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ These flags are available on all commands that interact with B2C instances:
4747
- [Sandbox Commands](./sandbox) - Create and manage On-Demand Sandboxes
4848
- [MRT Commands](./mrt) - Manage Managed Runtime (MRT) projects and deployments
4949
- [SLAS Commands](./slas) - Manage Shopper Login and Access Service (SLAS) API clients
50+
- [CIP Commands](./cip) - Run CIP SQL queries and curated analytics reports
5051
- [Custom APIs](./custom-apis) - SCAPI Custom API endpoint status
5152

5253
### Development

0 commit comments

Comments
 (0)