mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-09 08:53:18 +08:00
b26d254871
Adds a skill for authoring Tableau Next semantic models (SDMs) on Data 360: build from scratch, add data objects, define joins, enrich with calculated fields and metrics, and make models AI-ready. Smoke-tested against a live Data 360 org: SDM discovery, AI-readiness flip, dimension creation, metric creation, and description backfill all exercised end-to-end.
138 lines
4.3 KiB
Markdown
138 lines
4.3 KiB
Markdown
# Tableau Next Semantic Model Generate
|
|
|
|
Build and enrich Semantic Data Models on Salesforce Data 360, powering the Tableau Next semantic layer. Author an SDM from scratch — create a model on an existing DLO/DMO, add data objects, and join them with model-level relationships — or enrich an existing SDM with calculated fields, dimensions, and metrics.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 1. Discover available SDMs
|
|
python scripts/discover_sdm.py --list
|
|
|
|
# 2. Inspect SDM structure
|
|
python scripts/discover_sdm.py --sdm Sales_Cloud12_backward --json
|
|
|
|
# 3. Create calculated field
|
|
python scripts/create_calc_field.py \
|
|
--sdm Sales_Cloud12_backward \
|
|
--type measurement \
|
|
--name Win_Rate_clc \
|
|
--label "Win Rate" \
|
|
--expression "SUM([Won_Count]) / SUM([Total_Count])" \
|
|
--aggregation UserAgg
|
|
|
|
# 4. Create metric referencing the calculated field
|
|
python scripts/create_metric.py \
|
|
--sdm Sales_Cloud12_backward \
|
|
--name Win_Rate_mtc \
|
|
--label "Win Rate" \
|
|
--calculated-field Win_Rate_clc \
|
|
--time-field Close_Date \
|
|
--time-table Opportunity_TAB_Sales_Cloud
|
|
```
|
|
|
|
## What This Skill Does
|
|
|
|
- **Discover** — List SDMs and inspect objects, fields, and relationships
|
|
- **Build an SDM from scratch** — Create a model on an existing DLO/DMO (anchor + incremental), add data objects, and join them with model-level relationships
|
|
- **Create calculated fields** — Add custom business logic (measurements and dimensions)
|
|
- **Create metrics** — Build time-based KPIs for Tableau Next dashboards
|
|
- **Validate** — Check Tableau expressions and structural payloads before POSTing
|
|
|
|
**Out of scope:** creating DLOs/DMOs, data streams, DLO→DMO mapping, and logical views (UI-only).
|
|
|
|
## When to Use
|
|
|
|
Use this skill **before** building Tableau Next dashboards when you need:
|
|
- Custom business logic (win rates, conversion rates, weighted pipelines)
|
|
- Categorical dimensions derived from other fields
|
|
- Reusable metrics across multiple dashboards
|
|
- Standardized business definitions on the semantic layer
|
|
|
|
## Scripts
|
|
|
|
All scripts live under `scripts/` and share library modules from `scripts/_shared/`. Verify the layout with:
|
|
|
|
```bash
|
|
python scripts/_shared/verify_paths.py
|
|
```
|
|
|
|
## Prerequisites
|
|
|
|
- Salesforce CLI (`sf`) authenticated to a Data 360-enabled org with semantic model access
|
|
- Python 3.8+ with the `requests` library (`pip install -r scripts/requirements.txt`)
|
|
- `jq` for JSON parsing
|
|
|
|
**Quick setup:**
|
|
```bash
|
|
export SF_ORG=myorg
|
|
export SF_TOKEN=$(sf org auth show-access-token --target-org $SF_ORG --json | jq -r '.result.accessToken')
|
|
export SF_INSTANCE=$(sf org display --target-org $SF_ORG --json | jq -r '.result.instanceUrl')
|
|
```
|
|
|
|
## Common Use Cases
|
|
|
|
### Create a Win Rate Metric
|
|
|
|
```bash
|
|
# Step 1: Create calculated field
|
|
python scripts/create_calc_field.py \
|
|
--sdm Sales_Cloud12_backward \
|
|
--type measurement \
|
|
--name Win_Rate_clc \
|
|
--label "Win Rate" \
|
|
--expression "SUM([Won_Count]) / SUM([Total_Count])" \
|
|
--aggregation UserAgg
|
|
|
|
# Step 2: Create metric
|
|
python scripts/create_metric.py \
|
|
--sdm Sales_Cloud12_backward \
|
|
--name Win_Rate_mtc \
|
|
--label "Win Rate" \
|
|
--calculated-field Win_Rate_clc \
|
|
--time-field Close_Date \
|
|
--time-table Opportunity_TAB_Sales_Cloud
|
|
```
|
|
|
|
### Create a Metric with Breakdown Dimensions
|
|
|
|
```bash
|
|
python scripts/create_metric.py \
|
|
--sdm Sales_Cloud12_backward \
|
|
--name Revenue_by_Region_mtc \
|
|
--label "Revenue by Region" \
|
|
--calculated-field Total_Revenue_clc \
|
|
--time-field Close_Date \
|
|
--time-table Opportunity_TAB_Sales_Cloud \
|
|
--additional-dimension "Region:Opportunity_TAB_Sales_Cloud" \
|
|
--additional-dimension "Industry:Account_TAB_Sales_Cloud"
|
|
```
|
|
|
|
### Create a Categorical Dimension
|
|
|
|
```bash
|
|
python scripts/create_calc_field.py \
|
|
--sdm Sales_Cloud12_backward \
|
|
--type dimension \
|
|
--name Deal_Size_Category_clc \
|
|
--label "Deal Size Category" \
|
|
--expression "IF [Amount] > 100000 THEN 'Large' ELSEIF [Amount] > 50000 THEN 'Medium' ELSE 'Small' END"
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
After enriching the semantic layer:
|
|
- **Build visualizations** — Reference your new calculated fields when authoring Tableau Next visualizations
|
|
- **Build dashboards** — Reference metrics in Tableau Next dashboard KPI widgets
|
|
|
|
## Documentation
|
|
|
|
See [SKILL.md](SKILL.md) for complete documentation including:
|
|
- Discovery workflow
|
|
- Calculated field patterns
|
|
- Metric design best practices
|
|
- Tableau function reference
|
|
- Common errors and fixes
|
|
|
|
---
|
|
|