analytics-dashboard-json

# CRM Analytics Dashboard JSON

This skill activates when a practitioner needs to edit a CRM Analytics dashboard's JSON body directly — covering SAQL/SOQL step construction, binding syntax, layout manipulation, step parameters, and the REST API workflow for GET/PUT operations. It does not cover the standard dashboard builder UI or dataset design.

---

## Before Starting

Gather this context before working on anything in this domain:

- Retrieve the current dashboard JSON via `GET /services/data/vXX.X/wave/dashboards/{dashboardId}` and inspect the `state`, `steps`, and `widgets` top-level keys before making any edits.
- Identify dataset references: practitioners commonly assume dataset name is sufficient — it is not. You need `datasetId` and `datasetVersionId` from `GET /services/data/vXX.X/wave/datasets` to construct portable SAQL steps.
- Know the row limit in play: SAQL steps default to 2,000 rows. If a downstream binding or widget depends on a full population, the default will silently truncate results without any error.

---

## Core Concepts

### Dashboard JSON Structure

Every CRM Analytics dashboard body is a JSON document with three top-level sections:

**`steps`** — A map of named query definitions. Each step runs a SAQL or SOQL query against a dataset and holds its results in memory for widget binding. Steps declare their `query` (SAQL string or SOQL string), `type` (`saql` or `soql`), `datasets` array, and optional `limit` property. The `limit` defaults to 2,000 rows and can be raised to a maximum of 10,000 per step.

**`widgets`** — A map of named visual components. Each widget specifies its `type` (chart, table, filter, text, etc.), its pixel-based `layout` (top, left, width, height in pixels), and its `parameters` object which maps widget inputs (e.g., `measures`, `dimensions`, `filters`) to step results via binding expressions.

**`state`** — A map of global selections, active filters, and interaction state. State carries the current user selection from one widget so that other widgets can read it via bindings. State is modified at runtime by user interaction and can be pre-seeded with default values.

### Binding Syntax

Bindings are mustache-delimited expressions embedded in widget `parameters` values. They read from either step results or selection state at render time.

The canonical cell-level binding form is:

```
{{cell(stepName.selection, 0, "fieldName")}}
```

- `stepName` — the key in the `steps` map
- `.selection` — reads the user's current selection in that step
- `0` — the row index (zero-based)
- `"fieldName"` — the field to extract

An empty binding (when the referenced cell has no value, such as when no selection has been made) returns an empty string, not an error or null. This causes silent suppression: a filter widget whose bound value is empty will produce no filter clause, which may return unintended full-population results rather than an empty result set.

Array bindings for multi-select filters use:

```
{{#arrayToObject}}...{{/arrayToObject}}
```

or the `columnMap` binding form for mapping multiple fields simultaneously.

### Dataset References in SAQL Steps

SAQL steps reference datasets inside the `datasets` array of the step definition. The `name` field in the datasets array is the display alias used in the SAQL query body. The **`id`** and **`label`** fields, however, must use the `datasetId` and `datasetVersionId` obtained from the dataset API — not the human-readable dataset name used in the UI.

Using only the dataset name instead of the `id`/`version` pair causes the step to resolve by name lookup at render time. This works in a single org but breaks silently when the dashboard is migrated, cloned into a sandbox, or deployed via Metadata API — because dataset IDs differ across orgs and the name may not match. The SAQL step returns no results rather than an error.

### REST API Versioning

CRM Analytics dashboards are versioned via the History API. Every `PUT /services/data/vXX.X/wave/dashboards/{dashboardId}` call that modifies the dashboard body automatically creates a new history snapshot. Previous versions are accessible at:

```
GET /services/data/vXX.X/wave/dashboards/{dashboardId}/histories
```

This means every PUT is non-destructive — the prior version is always recoverable. However, there is no built-in diff view; practitioners must compare full JSON bodies manually or via script.

---

## Common Patterns

### Cross-Widget Binding via Selection State

**When to use:** A filter widget (list selector, range slider) in one part of the dashboard should drive the data shown in charts or tables elsewhere, across datasets.

**How it works:**
1. Define a step for the filter source dataset. Set `selectionFields` to the field you want to expose (e.g., `["Account.Industry"]`).
2. In the target chart step's SAQL query, add a `where` clause that reads the binding:
   ```
   | filter 'Industry' in ["{{#each cell(filterStep.selection, 0, "Industry")}}{{this}}{{/each}}"]
   ```
3. In the target widget's `parameters`, bind `filters` to the selection state of the source step.
4. Test with no selection (binding returns empty string) to confirm the default behavior is acceptable.

**Why not hardcode values:** Hardcoded filter values cannot be driven by user interaction. Faceting (automatic cross-filtering) only works within the same dataset; cross-dataset filtering requires explicit bindings in JSON.

### Raising SAQL Step Row Limits

**When to use:** A step backing a table or export widget needs to surface more than 2,000 records, or a step used as a binding source needs a full population to avoid silent truncation.

**How it works:**
Add the `limit` property to the step definition in the `steps` map:

```json
"myStep": {
  "type": "saql",
  "query": "q = load \"datasetId/datasetVersionId\"; q = limit q 10000; q;",
  "datasets": [...],
  "limit": 10000
}
```

Both the `limit` property on the step object and the `limit` clause in the SAQL query string must be set. The platform enforces a hard maximum of 10,000 rows per step regardless of the value set.

**Why not rely on default:** The 2,000-row default is silently applied. There is no UI warning when results are truncated — the widget renders with partial data and no error message.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| Filtering across two datasets | Explicit step binding using mustache cell() expression | Faceting only works within a single dataset |
| Dashboard migration across orgs | Use datasetId + datasetVersionId in SAQL step datasets array | Name-based resolution fails silently in target org |
| Need more than 2,000 rows in a step | Set `limit: 10000` on step AND add `limit 10000` in SAQL query | Both must be set; SAQL alone or property alone is insufficient |
| Recovering a prior dashboard version | GET /wave/dashboards/{id}/histories and re-PUT the desired body | PUT auto-creates history; old versions are always accessible |
| Debugging an empty binding result | Check if the source selection step has an active user selection | Empty binding = empty string, not error; no selection = no value |

---

## Recommended Workflow

Step-by-step instructions for an AI agent or practitioner editing dashboard JSON:

1. **Retrieve the current dashboard body** via `GET /services/data/vXX.X/wave/dashboards/{dashboardId}`. Save the full JSON response as a working copy before making any changes — the History API preserves versions after PUT, but having a local baseline is essential for diffing.
2. **Resolve dataset identifiers** via `GET /services/data/vXX.X/wave/datasets` before constructing or modifying any SAQL step. Record the `id` (datasetId) and the `currentVersionId` (datasetVersionId) for every dataset the dashboard queries. Do not use display names.
3. **Edit steps first, then widgets, then state.** Steps are referenced by name from widgets; editing in this order avoids forward-reference confusion. When adding a new step, assign it a camelCase key in the `steps` map and verify it is unique.
4. **Construct bindings using the exact mustache syntax** `{{cell(stepName.selection, 0, "fieldName")}}`. Test the empty-binding case: when no selection exists, the binding returns an empty string. Decide explicitly whether an empty binding should produce no filter (full population) or a zero-result filter, and handle accordingly in the SAQL where clause.
5. **Set explicit row limits** on any step where truncation matters. Add both `"limit": 10000` to the step object and `limit 10000` to the SAQL query string. The platform maximum is 10,000 rows per step.
6. **PUT the modified body** via `PUT /services/data/vXX.X/wave/dashboards/{dashboardId}` with `Content-Type: application/json`. The platform automatically creates a history snapshot. Verify the response `id` and `lastModifiedDate` match expectations.
7. **Validate in the dashboard UI** by opening the dashboard, triggering every filter interaction, and confirming that cross-widget bindings resolve correctly and no widgets show empty or unexpected results.

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] All SAQL steps reference datasets by `datasetId` and `datasetVersionId`, not by display name
- [ ] All mustache binding expressions use the exact form `{{cell(stepName.selection, 0, "fieldName")}}`
- [ ] Empty-binding behavior (no active selection) is explicitly handled for all filter-driven steps
- [ ] Any step returning more than 2,000 rows has `"limit"` set on the step object and in the SAQL query string
- [ ] The dashboard JSON was retrieved via REST API before editing and the full body was PUT back (not a partial update)
- [ ] History API was confirmed to have a new snapshot after the PUT (verify via GET /histories)
- [ ] Cross-widget filter interactions were tested end-to-end in the dashboard UI

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **Dataset name resolution fails silently across orgs** — Using the dataset display name instead of `datasetId`/`datasetVersionId` in a SAQL step's datasets array works in the authoring org but resolves by name lookup at render time. When the dashboard is deployed to another org or sandbox, the name may not exist or may point to a different dataset. The step returns no results — no error is thrown, no warning is displayed.
2. **Empty bindings return empty string, not null or error** — When a binding's source step has no active user selection, `{{cell(stepName.selection, 0, "fieldName")}}` returns an empty string. A SAQL `where` clause built around this value may behave differently than intended: some constructs silently drop the filter (returning the full population) while others produce a literal empty-string comparison that returns zero rows.
3. **SAQL step row limit defaults to 2,000 with no UI warning** — Truncation is silent. A step returning exactly 2,000 rows is almost always truncated. Widgets render partial data with no indicator. The maximum is 10,000, and both the step-level `limit` property and the SAQL `limit` clause must be set explicitly.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| Modified dashboard JSON body | Full dashboard JSON ready for PUT to /wave/dashboards/{id} |
| SAQL step definitions | Step objects with datasetId/datasetVersionId references, explicit limits, and query strings |
| Binding expressions | Mustache cell() expressions for cross-widget filter wiring |

---

## Related Skills

- admin/analytics-dashboard-design — Design-level decisions (chart type selection, faceting, layout structure) that precede JSON editing