PranavNagrecha/AwesomeSalesforceSkills / skills/admin/analytics-recipe-design
analytics-recipe-design
VerifiedUse this skill when designing or building CRM Analytics Data Prep recipes — including node selection, join patterns, bucket field configuration, formula expressions, and scheduling. Triggers: 'build a recipe', 'join datasets in analytics', 'bucket a measure field', 'schedule a recipe', 'data prep transformation'. NOT for dataflow JSON and its node types — use admin/analytics-dataflow-development. NOT for tuning a slow or oversized dataset — use data/analytics-dataset-optimization.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.5 KB |
| references/examples.md | markdown | 7.3 KB |
| references/gotchas.md | markdown | 10.5 KB |
| references/llm-anti-patterns.md | markdown | 7.5 KB |
| references/metadata-examples.md | markdown | 7.3 KB |
| references/well-architected.md | markdown | 7.7 KB |
| scripts/check_analytics_recipe_design.pyexecutable | script | 8.8 KB |
| templates/analytics-recipe-design-template.md | markdown | 4.3 KB |
references/metadata-examples.md
View on GitHub# Metadata Examples: Analytics Recipe Design
A deployable worked example for the Lookup-enrichment recipe in `examples.md` Example 1: an Opportunity dataset enriched with Account industry, protected by a row-level predicate, scheduled after the local sync, and promoted between orgs.
Grounding: Metadata API Developer Guide, WaveRecipe and WaveApplication (`api_meta L138986-139058`, `L138608-138650`); Data Prep Recipe REST API Developer Guide (`salesforce_recipes_api L420-616`, Join Parameters Input `L2770-2795`); CRM Analytics REST API Developer Guide, Schedule resource (`bi_dev_guide_rest L1480-1570`, `L6266-6300`). Element names not found in those guides are marked UNVERIFIED.
## 1. Recipe metadata
`WaveRecipe` extends `MetadataWithContent`, uses the `.wdpr` suffix, and lives in the `wave` folder (API 41.0 and later). The recipe body is the content file; the fields below are the metadata.
`force-app/main/default/wave/Opportunity_Enriched.wdpr-meta.xml`
```xml
<?xml version="1.0" encoding="UTF-8"?>
<WaveRecipe xmlns="http://soap.sforce.com/2006/04/metadata">
<application>Sales_Analytics</application>
<dataflow>02KB0000000b5c7MAA</dataflow>
<format>R3</format>
<masterLabel>Opportunity Enriched</masterLabel>
<securityPredicate>'OwnerId' == "$User.Id"</securityPredicate>
<targetDatasetAlias>Opportunity_Enriched</targetDatasetAlias>
</WaveRecipe>
```
| Element | Value here | Notes |
|---|---|---|
| `application` | `Sales_Analytics` | Internal name of the Analytics app that holds the recipe |
| `dataflow` | `02KB...` | Required. The recipe's dataflow ID. Retrieve it from the source org; do not type it. UNVERIFIED (2026-10-03): how a target org resolves a source-org ID on deploy |
| `format` | `R3` | Recipes created at API 48 or later can only be R3 (`salesforce_recipes_api L459`) |
| `masterLabel` | `Opportunity Enriched` | Required. Name shown in the UI |
| `securityPredicate` | owner predicate | Applies when the dataset is created; later edits in the recipe have no effect (gotcha 5) |
| `targetDatasetAlias` | `Opportunity_Enriched` | Dataset the recipe writes |
UNVERIFIED (2026-10-03): the guide's sample shows `<content xsi:nil="true"/>` inside `WaveRecipe`. In source format the content travels as `Opportunity_Enriched.wdpr` beside this file, following the usual `MetadataWithContent` pattern; retrieve the pair rather than authoring the content file by hand.
## 2. The app that shares the dataset
`force-app/main/default/wave/Sales_Analytics.wapp-meta.xml`
```xml
<?xml version="1.0" encoding="UTF-8"?>
<WaveApplication xmlns="http://soap.sforce.com/2006/04/metadata">
<assetIcon>/analytics/wave/web/proto/images/app/icons/11.png</assetIcon>
<description>Opportunity datasets enriched with Account attributes</description>
<folder>Sales_Analytics</folder>
<masterLabel>Sales Analytics</masterLabel>
<shares>
<accessLevel>View</accessLevel>
<sharedTo>Sales_Reps</sharedTo>
<sharedToType>Group</sharedToType>
</shares>
<shares>
<accessLevel>Manage</accessLevel>
<sharedTo>Analytics_Admins</sharedTo>
<sharedToType>Group</sharedToType>
</shares>
</WaveApplication>
```
App sharing decides who can open the dataset. The security predicate decides which rows they see. Both are needed.
## 3. package.xml
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<types>
<members>Sales_Analytics</members>
<name>WaveApplication</name>
</types>
<types>
<members>Opportunity_Enriched</members>
<name>WaveDataflow</name>
</types>
<types>
<members>Opportunity_Enriched</members>
<name>WaveRecipe</name>
</types>
<version>67.0</version>
</Package>
```
The `WaveDataflow` member is listed by name because wildcard retrieval of `WaveRecipe` "doesn't return the recipe's associated dataflows". UNVERIFIED (2026-10-03): the recipe's dataflow API name is assumed to match the recipe name here; read the real name from a retrieve of the source org.
## 4. What the recipe definition looks like over REST
`GET /services/data/v67.0/wave/recipes/05vB0000000xxxxxxx?format=R3` returns the definition. This excerpt shows the node map for the enrichment design. Review it; do not hand-author it for a POST, because `recipeDefinition` also requires a `ui` object that Data Manager writes.
```json
{
"format": "R3",
"recipeDefinition": {
"name": "Opportunity_Enriched",
"runMode": "Full",
"version": "67.0",
"nodes": {
"LOAD_OPPS": {
"action": "load",
"parameters": {
"dataset": { "label": "Opportunities", "name": "opportunity", "type": "analyticsDataset" },
"fields": ["Id", "AccountId", "Amount", "StageName", "CloseDate"]
},
"sources": []
},
"LOAD_ACCOUNTS": {
"action": "load",
"parameters": {
"dataset": { "label": "Accounts", "name": "account", "type": "analyticsDataset" },
"fields": ["Id", "Industry", "AnnualRevenue"]
},
"sources": []
},
"JOIN_ACCOUNT": {
"action": "join",
"parameters": {
"joinType": "Lookup",
"leftKeys": ["AccountId"],
"leftQualifier": "Opportunity",
"rightKeys": ["Id"],
"rightQualifier": "Account"
},
"sources": ["LOAD_OPPS", "LOAD_ACCOUNTS"]
},
"OUTPUT0": {
"action": "save",
"parameters": {
"dataset": { "folderName": "Sales_Analytics", "label": "Opportunity Enriched", "name": "Opportunity_Enriched", "type": "analyticsDataset" },
"fields": []
},
"sources": ["JOIN_ACCOUNT"]
}
}
},
"targetDataflowId": "02KB000000xxxxxxxx"
}
```
`joinType`, `leftKeys`, `leftQualifier`, `rightKeys`, and `rightQualifier` are the required Join Parameters Input properties. The load and save shapes follow the guide's Inspect Recipe Nodes example. UNVERIFIED (2026-10-03): the exact casing of the `action` value for joins in a GET response (`join`) is inferred from the guide's lowercase `load`, `filter`, and `save` examples.
## 5. Schedule and run after deploy
Schedules are not part of the metadata. Recreate the schedule in each target org.
```bash
# Event-based: run after the Salesforce Local connection syncs
curl -X PUT "$INSTANCE/services/data/v67.0/wave/asset/05vB0000000xxxxxxx/schedule" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"frequency":"eventdriven","triggerRule":"$ALL_SALESFORCE_OBJECTS"}'
# First run now, using the targetDataflowId from the GET above
curl -X POST "$INSTANCE/services/data/v67.0/wave/dataflowjobs" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"dataflowId":"02KB000000xxxxxxxx","command":"start"}'
```
## Deploy order
1. Public groups named in the app shares (`Sales_Reps`, `Analytics_Admins`).
2. `WaveApplication`.
3. `WaveDataflow` and `WaveRecipe` together.
4. Schedule (REST, per org).
## Verification
- `GET /wave/recipes/<id>?format=R3` in the target org returns the recipe with `"format":"R3"` and a `targetDataflowId`.
- `GET /wave/asset/<id>/schedule` returns the event-based schedule.
- After the first job, the output dataset row count equals the Opportunity input row count (Lookup keeps every left row).
- A user outside the predicate sees no rows they do not own.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |