ClaudforceHLS · Provider + Payer

---
name: claudforce-hls-rebuild
description: Use when the user wants to build, rebuild or stand up a healthcare Salesforce demo org with Data Cloud, Marketing Cloud Next and Agentforce, or asks to follow the Claudforce HLS rebuild path.
---

# Claudforce HLS rebuild

Routing only. The material lives in the tools, not here. Do not restate the guide.

## Two servers

- **Claudforce HLS MCP** carries the knowledge: the ordered route, the verified traps, the skills,
  the dataset shapes, the verifications. It has no access to any Salesforce org and never will.
- **Salesforce MCP**, connected to the org being built in, issues every call.

If only one is connected, stop and say which is missing. Neither half builds anything alone.

## Procedure

1. Call `start_here` before anything else.
2. Read the route: `get_guide`, or `list_sections` then `get_section`.
3. Build the data foundation first, in the documented order, before dashboards, components or
   agents. Everything downstream inherits its defects.
4. Before each Data Cloud step, call `search_traps` filtered to that surface. Read the result
   before issuing the call, not after it fails.
5. After each step, call `verify_step` and run the query it returns against the target org.
   Reconcile the result against the stated expectation. Report any gap as a finding.
6. Never trust a status code. A 200 means the parser accepted the request. Several operations in
   this build create on a 500, succeed while doing nothing, or discard half the payload.
7. Resolve every org anchor at runtime: record ids, DMO names, ruleset ids, graph epochs, content
   keys. Ids in the guide belong to the org it was written from. Query for the anchor, never reuse
   one from documentation.
8. `get_dataset_schema` before loading data, `get_manifest` before trusting a download's contents,
   `get_skill` for the surface-specific procedures.

## Stop conditions

- A verification fails and you cannot explain the gap. Report it; do not proceed downstream.
- A step has no verification available. Say so explicitly rather than declaring it done.
- An anchor cannot be resolved from the target org. Ask; do not guess a value.

---
name: salesforce-se-os
description: One triage entry point for Solutions Engineer work, built to run off call transcripts and pasted context rather than a live CRM connection. Use this skill whenever the user wants to analyze a customer call, build a follow-up, plan next steps, prep for an upcoming conversation, research a product/competitor/technical topic, or scope a Salesforce solution. Trigger on phrases like "analyze this call", "what did I miss on this call", "draft a follow-up", "prep me for [account]", "what do I need to know before [meeting]", "what does this customer actually need", "how would I solution [use case]", "research [topic/competitor]", or any customer-conversation, follow-up, planning, research, or solutioning ask — even when the user doesn't name which mode they want. The skill self-routes and shows the routing decision back. Built for a marketing-focused SE who covers all clouds, so assume multi-cloud solutions are common. Always use this over generic prep, note-summarizing, or research when the request is SE-shaped.
---

# Salesforce SE OS

One entry point for Solutions Engineer work. Read the request, route it to the right mode, and always show the routing decision back so the user can see what was chosen and what was rejected.

**This skill runs off what the user gives you — call transcripts, notes, emails, deal descriptions, and pasted context — not a live CRM.** Claude is not connected to Salesforce CRM here. Treat transcripts and pasted context as the primary source of truth. If the user happens to paste CRM fields, use them; otherwise never assume CRM data exists and never invent it.

The user is a Solutions Engineer at Salesforce, marketing-focused but covering all clouds. Solutions frequently span more than one cloud (e.g. Marketing Cloud + Data Cloud + core Sales/Service), so never assume a single-cloud answer is complete without checking whether adjacent clouds are in play.

## The revenue + customer-success lens

Every output should name **both** sides, kept honest:

- **The customer need** — what the customer actually said they need, in their words, grounded in the transcript.
- **The Salesforce angle** — how solving that need maps to revenue (expansion, new cloud, retention) *and* to the customer's own success.

Keep the two aligned. The revenue angle must follow from a real need in the transcript — never manufacture urgency or an expansion story the call doesn't support. A follow-up that overreaches past what the customer said damages trust and the deal. When the transcript doesn't support a revenue angle, say so plainly and keep the focus on the need.

## How it works

- **Always available (no integrations):** Reasoning over whatever the user pastes — transcripts, call notes, emails, deal descriptions, product docs — plus general product and market knowledge.
- **If connected (web search, uploaded files, or user-provided context):** Live web and developer-doc search, enablement content, and any CRM fields the user chooses to paste.
- If a source isn't available, don't fabricate it. Say so in the footer and continue with what's provided.

## Phase 1 — Triage

Classify the request into exactly one mode:

- **Call Analysis** — "analyze this call", "what did I miss", "what were the signals", "summarize this transcript". Input is a transcript or notes.
- **Follow-up / Planning** — "draft a follow-up", "what are my next steps", "build the plan for this account", "what should I send". Turns a call or context into action.
- **Conversation Prep** — an upcoming call, meeting, or QBR, or "what do I need to know about [account]" before talking to them.
- **Research** — a product, market, competitor, or technical topic with no specific call tied to it.
- **Solutioning** — designing, scoping, or troubleshooting a solution or use case for a customer.
- **General/Unclear** — doesn't cleanly fit, or spans more than one.

Capture any account, topic, or use case named. If mode is ambiguous **and** no transcript/context/topic is given, ask one bundled question: "What's this for — analyzing a call, building a follow-up or plan, prepping for a conversation, research, or scoping a solution? And can you paste the transcript or context?"

If context is given but mode is unclear, infer the most likely mode and proceed — state the assumption in the footer rather than asking.

If the request spans two modes ("analyze this call and draft the follow-up"), run both phases and combine into one output with two sections. Call Analysis feeding Follow-up is the most common pairing — expect it.

**Log the fork as you go.** This skill's whole point is showing its work, so track not just what you chose but what you considered and rejected. For each decision, note in one short line (under ~15 words) *why* — which words in the request or which line in the transcript triggered it. This feeds the mandatory Triage Rationale table. Capture:

- The mode chosen **and** the modes considered but dropped, with the reason each was dropped.
- Sources used vs. skipped, and why each was skipped (unavailable, not relevant, out of scope).
- Items included vs. notable items excluded, and why the excluded ones didn't make the cut.

The rejected side matters as much as the chosen side — it's how the user checks whether the skill routed correctly.

## Phase 2 — Gather (mode-specific)

**Call Analysis:**
- Work from the transcript or notes the user pasted. Pull out: stated needs and pains, explicit and implicit requirements, objections, buying/expansion signals, competitor mentions, who was in the room and their apparent role, and any commitments made by either side.
- Separate what the customer *said* from what you're *inferring*. Label inferences as such.
- Don't invent details the transcript doesn't contain. Gaps are findings too — flag what wasn't covered but should have been.

**Follow-up / Planning:**
- Ground every action in something from the call or context — a stated need, an open question, a commitment made. Quote or reference the source line.
- Draft follow-ups (email, next-step list, mutual plan) that reflect what the customer actually asked for. Surface any commitment the SE made on the call so it doesn't get dropped.
- Flag open questions the SE still needs answered before the deal can progress.

**Conversation Prep:**
- Work from whatever the user pastes about the account — prior call notes, email threads, context. If they paste CRM fields (opportunities, amounts, stages), use them; otherwise proceed on context alone and note the absence in the footer.
- Surface: what's known about the account's needs, open threads from last contact, and what to confirm or advance in this conversation.

**Research:**
- Search the web and connected enablement content for the topic.
- For anything technical, search Salesforce developer documentation dynamically — see "Developer documentation search" below.
- No external search available → rely on general knowledge but label it unverified rather than sourced fact.

**Solutioning:**
- Work from the requirement as described in the transcript or context. Restate the use case in your own words and confirm it against what the customer said.
- Identify **which clouds the requirement touches** before searching — marketing use cases routinely pull in Data Cloud for unified profiles, core platform for records, and Service or Commerce depending on the flow. Name the cloud combination explicitly.
- Search for relevant solution patterns, architecture references, and product capabilities — see "Developer documentation search" below. Label the source of each.

### Developer documentation search

For Research and Solutioning, search Salesforce technical sources **dynamically** rather than citing a fixed link list — the right page depends on the clouds in play. When web search is available, search live and cite what you find; when it isn't, point the user to the right hub to search themselves and label it as a pointer, not a sourced answer.

Match the source to the clouds the requirement touches. Common starting points:

- **Developer hub** — `developer.salesforce.com/docs` — the index for all API, Apex, and platform references.
- **Core platform** — Apex, SOQL/SOSL, REST API, Bulk API, Metadata API references under the developer hub.
- **Marketing Cloud** — Marketing Cloud Engagement APIs and SDKs; Marketing Cloud Growth on the core platform.
- **Data Cloud** — Data Cloud developer docs (data model, ingestion, identity resolution, calculated insights) — where most modern marketing solutioning lands.
- **Reference architectures** — `architect.salesforce.com` — for solution patterns and multi-cloud blueprints.
- **Enablement framing** — Trailhead — for how to position or explain a capability.

Because solutions often span clouds, expect to search more than one of these for a single requirement, and surface related links across them rather than stopping at the first cloud that fits. Prefer live search results over general knowledge whenever search is available.

## Phase 3 — Synthesize

- Ground everything in the transcript or pasted context. Never invent financial figures, dates, stages, or commitments — if the user pasted them, use them; if not, mark "[not in transcript]" rather than guessing.
- Apply the revenue + customer-success lens: for the needs surfaced, name both the customer's success outcome and the Salesforce revenue angle, kept honest against what the call supports.
- For Research and Solutioning, tie findings back to the customer need they address (e.g. "this answers the identity-resolution need the customer raised at [point in call]"). If no need is tied, state findings as general enablement.
- For multi-cloud solutions, make the cloud dependencies explicit — which cloud owns which part of the flow — since that's where scoping and licensing questions surface.

## Phase 4 — Output

Match the output to the triaged mode, using this exact structure:

```
# [Mode]: [Account / Topic]

**Assumed mode:** [state only if inferred rather than confirmed; otherwise omit this line]

## Triage Rationale
(this is the audit — chosen vs. rejected, so you can see if it routed right)

| Decision | Chose | Rejected / skipped | Why |
|---|---|---|---|
| Mode | [mode chosen] | [modes considered and dropped] | [phrase/context that decided it] |
| Sources | [sources used] | [sources skipped, or "none"] | [why each was skipped] |
| Items | [items kept] | [notable items left out] | [why they were excluded] |

--- (if Call Analysis) ---

## What the customer said
[stated needs, pains, requirements, objections — grounded in the transcript, sourced to points in the call]

## Signals & inferences
[buying/expansion signals, competitor mentions, room dynamics — labeled as inference where not explicit]

## Gaps
[what wasn't covered but should have been]

--- (if Follow-up / Planning) ---

## Next steps
[each action tied to a source line from the call/context]

## Draft follow-up
[email or message reflecting what the customer actually asked for]

## Open questions
[what the SE still needs answered]

--- (if Conversation Prep) ---

## What's known
[account needs and open threads from prior context]

## Advance in this conversation
[what to confirm or move forward]

--- (if Research or Solutioning) ---

## Key Findings
[bulleted, each cited to source — live search / dev docs / architect.salesforce.com / general knowledge, labeled accordingly]

**Clouds involved:** [list the clouds the solution touches, or "single cloud: [name]"]

--- (all modes) ---

## Need + revenue lens
- **Customer need:** [what they actually need, from the transcript]
- **Salesforce angle:** [revenue + customer-success mapping, honest to what the call supports, or "transcript doesn't support a revenue angle yet"]

---

**Footer:** [sources used; anything skipped and why; assumptions made]
```

## Key principles

- Transcripts and pasted context are the source of truth. Claude is not connected to CRM — never assume or invent CRM data.
- Never invent financial figures, dates, stages, or commitments. Missing → "[not in transcript]".
- The revenue angle must follow from a real need in the call. Never manufacture urgency or an expansion story the transcript doesn't support — overreaching past what the customer said costs trust and the deal.
- The Triage Rationale table is mandatory on every run. Always show both the chosen and rejected side.
- Default to the mode the evidence supports; ask only when both mode and context are missing.
- Assume multi-cloud until proven otherwise for solutioning — surface adjacent clouds rather than stopping at the obvious one.
- Search developer docs dynamically and cite what you find; label general knowledge as such.

---
name: sfdc-headless-discovery
description: "Find an unknown Salesforce API contract instead of guessing or escalating to a human: the enumerators, the three oracles, route families to try in order, error messages that mislead, and the escalation gate. Use whenever a Salesforce step looks impossible over the API, a name or shape is unknown, a doc says something needs the UI, or you are about to hand a step back to the user."
---

# Headless discovery

Every "impossible over the API" met so far was one of six things: a missing request field, a wrong API version, an unexamined Aura call, a stale assumption in your own docs, a name guessed instead of enumerated, or **the wrong route family**. Zero were real capability gates. Read this before recording an impossibility or asking someone to click.

## The rule

When you do not know a NAME or a SHAPE, find the thing that ENUMERATES it. The tell that you are guessing: candidates are coming from intuition rather than from a response. Bulk guessing has never converged in practice (60 rejected definition names on one occasion, 32 on another); a single enumerator call has, repeatedly.

## Enumerators by question

| Question | Enumerator |
|---|---|
| What operations exist here? | MCP `discover` in plain words, then `describe` for the path and schema |
| What buttons does a record page have? | `GET /ui-api/actions/record/{id}` |
| Is there a standard invocable? | `GET /actions/standard`, grep the name. This is how segment publish was found (`cdpPublishSegment`) |
| Is the sObject writable where Connect is not? | `GET /sobjects/{Object}/describe` and check `updateable` per field |
| What components exist and what props? | `GET /component-catalog/components?target=...`, then `/component/{ns}/{name}/{Module or Component}/source` |
| What does a valid body look like? | GET a complete existing object of the same type, ideally one the UI created |
| What does the UI call? | Intercept `POST /aura`, read the descriptor, replay it |
| What DMOs and fields exist? | `GET /ssot/metadata?entityName=...` |

## The three oracles

1. **Schema oracle.** A strict validator with `additionalProperties: false` names every rejected and required property and lists enum values. Send `{}` to learn what is required; send a batch of guesses and whatever is not named as rejected is real.
2. **Processor oracle.** On a schema free `object`, a 500 means a recognised key with a wrong shape, and a transformed read back (HTML escaping) means recognised and processed. A 200 there proves nothing.
3. **Editor oracle, the cheapest and most overlooked.** The API only names keys you send; it never volunteers one. So the fastest schema source is an object the UI already wrote. SOQL the records of that type, GET one, diff against yours. Check this FIRST in a new org. It costs one query and one GET, and it has repeatedly beaten hours of probing.

## Route families, in order

1. Connect API (`/connect/...`, `/ssot/...`)
2. **Standard invocable actions** (`/actions/standard/{name}`, invoked with `{inputs:[{...}]}`)
3. sObject API, including objects that look internal (MarketSegment, FlowRecord, ManagedContentVariant)
4. Tooling API, including `MetadataContainer` for in place Apex updates and `PackageInstallRequest` for managed packages
5. Aura capture and replay (needs a browser)

Metadata API deploys are not reachable through the MCP connector, so custom objects and org wide overrides stay clicks.

**Two routes that solved things a "proper" route could not:**
- `PackageInstallRequest` installed a data kit that the product's own deploy endpoint silently no-opped on, and unlike that endpoint it has a real per request status reader.
- `MetadataContainer` plus `ApexClassMember` plus `ContainerAsyncRequest` updates Apex in place when a `Body` PATCH is refused, without deleting a class other components depend on.

## Errors that are not what they say

| Message | Meaning |
|---|---|
| `Set the segmentType to Dbt or Lookalike` | You did not send `segmentType` |
| `Expected referredColumns to be not empty` | This route cannot write; use the sObject route |
| `500 Internal error` on a data graph write | It committed. GET before retrying |
| `No such column` right after a 201 field create | FLS. Grant it on a standalone permission set |
| Aura `200` with `actions:[]` | Wrong descriptor, or stale captured token |
| `INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY` on a Tooling Apex Body PATCH | Use MetadataContainer |
| `AURA_COMPILE_ERROR ... missing label` on an LWC bundle POST | You sent `targetConfigs` as raw XML, or a `.js-meta.xml` |
| A list route 404 | It may need a filter parameter to serve at all. `data-model-object-mappings` only responds with `?dmoDeveloperName=` |
| Any `200` or `SUCCESS` | Nothing. Verify with an independent read |

An error naming a field is a missing field error, not a capability gate.

## Small traps that cost real time

- A `+` in an `executeAnonymous` query string decodes as a space and the compile error points at the wrong token. Build output with a `List<String>` and `String.join`.
- A `throw` in `executeAnonymous` rolls back all DML in that block.
- Never send back HTML that a GET returned. Where a write applies a sanitizer plus an escape, the correct inverse is to unescape until stable, and it must cover every text bearing field including URLs.
- `FieldPermissions` cannot be written to a permission set inside a permission set group.
- A record page that sets `parentFlexiPage` inherits regions you cannot edit or remove, and the parent may not exist in Tooling at all. Build standalone if you need control of the whole page.
- Some list endpoints page at 10 regardless of `limit` and 500 on a larger one. Read by name instead.

## When a subagent or a long run is involved

Cap each unit at roughly 20 to 25 calls and ten minutes, and report at the cap even if incomplete. A partial result with the exact blocking error is worth more than an overrun. State a hard rule that a run must not delete anything it did not create, because a delete-and-recreate that fails halfway leaves a worse state than not starting.

## Escalation gate

Hand a step to a human only when all five are true: the enumerator for this class was used and does not cover it; the newest API version was tried; the UI can do it and its captured call does not replay, or no browser is available and you say so; no OOTB or editor authored example exists to read; no equivalent route or outcome exists.

Then escalate the **cheapest possible action** ("build one in the UI once and I will read it back", "authorize the target once"), say exactly what you will do with it, and keep building everything around it.

## Doc hygiene and honesty

A documented impossibility that was never re-tested against a named endpoint is a hypothesis, not a fact. When you disprove one, correct the doc in the same pass with the route that worked, the exact body, and the trap that hid it.

Never report a UI outcome you have not seen. "Persisted and processor recognised" is a different claim from "renders in the editor", and conflating them wastes someone's afternoon.

---
name: sfdc-mcnext-campaign-build
description: "Build Marketing Cloud Next campaigns headlessly through the Salesforce MCP connector: campaign records, Data Cloud segments with criteria and publish, email and SMS content, Dynamic Content personalization points, Journey flows with real Path Experiment elements, campaign members, and mock engagement that actually renders in the OOTB dashboards. Use when asked to create, rebuild, or package a marketing campaign, segment, flow, email or SMS content, dynamic or personalized content, campaign goals, or mock engagement data in a Salesforce demo org."
---

# MC Next campaign build, headless

Every contract here ran live in a healthcare demo org on 2026-09-01/02 through `mcp__Salesforce_-_Beta__dispatch` alone. No browser, no CLI, no Data Kit. Six campaigns end to end took about 90 minutes once these traps were known. Read the traps before the steps.

## Operating rules

- Work in units of one campaign or one layer, each under ~25 API calls, and post a one line status after each. A silent 90 call agent reads as "stuck".
- Never delete anything that existed before the run. Segments cannot be deleted over the API; name probes `zz_`.
- A 200 or 201 is a claim. Read the object back and reconcile counts against an independent `POST /ssot/queryv2` at the same grain.
- Never send back text that a GET returned (see escaping below).
- **Long waits belong outside the run.** A data stream takes 5 to 11 minutes to surface rows and an identity resolution job takes 10 to 30. Fire those and check on a later turn; never sleep inside an agent waiting for them.
- No em dashes in any generated copy.

## Order

```
campaigns -> segments -> content -> dynamic content -> flows -> members and mock engagement -> web -> dashboards
```
Ids flow downstream: campaign ids into content UTMs, segment ids into flow starts, content keys into flow sends.

## Campaigns

`POST /services/data/v67.0/composite/sobjects` with Campaign records. Put the brief in `Description`; downstream agents read it for the content angle.

## Segments, fully headless

| Step | Call |
|---|---|
| Create | `POST /ssot/segments` `{displayName, segmentOnApiName, segmentType:"EinsteinGptSegmentsUI"}` |
| Criteria | `PATCH /sobjects/MarketSegment/{1sg}` `{"IncludeCriteria":"<JSON string>"}` -> 204 |
| Schedule | same PATCH: `PublishScheduleInterval`, `PublishScheduleStartDateTime`, `PublishType`, `PublishScheduleInfo` (JSON string) |
| Publish now | `POST /actions/standard/cdpPublishSegment` `{inputs:[{segmentId}]}` |

The Connect `PATCH /ssot/segments/{apiName}` cannot write anything, not even a rename: `referredColumns` is server derived. The sObject route is the write path. `saveAndCount` and the sObject route both silently ignore compound AND/OR criteria and count everyone, so one predicate per segment; for compound audiences compute a flag field on the CRM source and segment on `contains`. `GET /ssot/segments` 500s in some orgs; use SOQL `FIELDS(STANDARD) FROM MarketSegment`. An unpublished segment has no membership rows and will not appear on a contact card.

**The segment apiName is not on the sObject.** `MarketSegment` has no `DeveloperName` and no `ApiName`. The Data Cloud api name, which Dynamic Content targeting rules require, comes only from `GET /ssot/segments/{1sg id}` -> `segments[0].apiName`. It is the display name with non-alphanumeric runs collapsed to single underscores.

Profile DMO attributes are RELATED (three hops: Unified, UnifiedLink, ssot__Individual, profile DMO). Read the path off an existing segment; never guess it.

**Audience size is a design input.** A segment returning ten people cannot express a rate: opens, clicks and bounces all round to something absurd, and any guaranteed-minimum in the mock generator dominates. Widen the predicate before that campaign goes in a demo rather than inflating its data.

## Content

Create `POST /connect/cms/contents`, publish `POST /services/data/v62.0/connect/cms/contents/publish`. Flow reference is `marketing--Default_Content_Workspace.sfdc_cms__email--<contentKey>`.

Build from a generator with JSON specs, not by hand: subject <= 50 chars, H1 <= 9 words, one paragraph with `{!$recipient.FirstName}`, one `lightning/button` with `uri`, a three item list, plain language footer. SMS is `<Brand>: <benefit <= 20 chars> <link>?src=<code> Reply STOP to opt out.` at <= 160 chars with ONE query param.

**Image hosting is the biggest time sink.** `ContentVersion` needs base64 in JSON, so the model transcribes 15 to 45 KB per image and one will come back truncated. Host hero images on the public demo website instead and reference them from a `lightning/html` img tag. Upload only small assets like a logo (a 200px lockup is about 2 KB base64).

**A PUT on a content variant is a full replace and there is no PATCH** (the route allows DELETE, GET, HEAD, PUT). A partial body returns a bare 500 UNKNOWN_EXCEPTION, not a validation error. Send the complete `contentBody` including `sfdc_cms:block` on every write.

**Locate the hero block by `width="600"` in its rawHtml**, never by position. The logo is a `lightning/html` img on some emails and a `lightning/image` contentKey block on others, so "the first lightning/html block" picks the logo on half of them.

### The escaping algorithm, and its exact inverse

The API applies two stages on write: a URL sanitizer that rewrites `=` to `&#61;` and `&` to `&amp;` **inside quoted src and href values inside rawHtml only**, then a single HTML escape over the whole string. The `uri` of `lightning/button` never goes through stage one, which is why it stores a bare `=` and a single `&amp;`.

So the inverse is **one** html.unescape pass, then `&#61;` to `=` and `&amp;` to `&` inside quoted src and href values only.

Unescaping until the string stops changing is WRONG and silently destructive. Writing `<p>Base hero &amp; more</p>` stores `&lt;p&gt;Base hero &amp;amp; more&lt;/p&gt;`, so one pass returns the original and a second turns an intentional `&amp;` into a bare `&`. Write the inverse as a script, not by hand, and have it refuse to emit a body containing residual `&amp;amp;` or `&amp;#61;`.

The sanitizer also appends `noopener noreferrer` to every `rel` on every write, so collapse it to one pair on read; API written content then sits stably at two pairs. `&#39;` reappearing after a write is correct. `&amp;amp;` or `&amp;#61;` in a button `uri` is corruption.

### Publish returns 400 when there is nothing to publish

`POST /connect/cms/contents/publish` returns `400 INVALID_API_INPUT "Your content wasn't published. Try again."` when the pieces are already Published with no pending delta. Retrying, splitting the batch and changing API version never clear it. Verify with `status.status` and `isPublished` on the variant instead of trusting the publish call, and note a single deployment can flip pieces beyond the ids you listed.

## Dynamic Content, fully headless

Three objects, not one. The email holds no rule; it holds a name reference to a decision.

**Step 1, the personalization point.** `POST /services/data/v67.0/personalization/personalization-points`:

```json
{"name":"cld_<campaign>_<piece>_v1","label":"...","description":"email:<content title>",
 "dataSpaceName":"default","profileDataGraphName":"<the graph the email declares>",
 "schemaEnum":"ExperienceVariation","source":"BlockBuilder",
 "sourceRecordId":"<the ManagedContent 20Y id, NOT the 9Ps variant id>",
 "isAuthenticationRequired":false,
 "decisions":[{"name":"<decision>","label":"...","description":"...","state":"Live",
   "attributeValues":[{"attributeEnum":"Variation","value":"<the SAME decision name>"}],
   "targetingRules":{"operator":"And","type":"Group",
     "rules":[{"operator":"IsIn","segmentName":"<segment apiName>","type":"Segment"}]}}]}
```

Do not send `status`; it is rejected and server set, going Processing then Active in seconds. Priority is the decision's `Priority`. The Default or Fallback the editor shows is not a stored object, it is the base content. One point can hold several priority-ordered decisions when you want more than two creative variants on one email.

**Step 2, bind it on the email**, in the same full body PUT:

```json
"sfdc_cms:variants":[
 {"id":"<uuidA>","name":"<one variation name>","type":"personalization",
  "body":{"subjectLine":"...","preheader":"..."}},
 {"id":"<uuidB>","name":"<the SAME name>","type":"personalization",
  "body":{"sfdc_cms:block":{"children":[{"id":"<target block id>","definition":"lightning/html",
    "type":"block","attributes":{"rawHtml":"<img ... />"}}]}}}],
"sfdc_cms:operations":[
 {"definition":"sfdc_cms__pspVariantOperation",
  "attributes":{"personalizationPoint":{"dataspace":"default","name":"<point name>"},
    "decisionToVariantList":[{"decisionName":"<decision>","variantId":"<uuidA>"}]}},
 {"definition":"sfdc_cms__pspVariantOperation","targetId":"<target block id>",
  "attributes":{"personalizationPoint":{"dataspace":"default","name":"<point name>"},
    "decisionToVariantList":[{"decisionName":"<decision>","variantId":"<uuidB>"}]}}]
```

One variant per scope. Subject line and preheader are one scope, each overridden block is another; a variation touching both is two variants sharing one name, which is what the editor shows as Linked. `targetId` absent means email level, present means that block. The block level variant body is flat: `sfdc_cms:block.children[]` holds the overriding block with the SAME id, no section or column wrapper. `dataspace` is lowercase inside the operation and `dataSpaceName` is camelCase on the point; both are correct.

**`lightning:expressions[]` is not involved and stays empty**, including on editor authored variations. Guessing definition names there is the classic dead end; the definition you want is `sfdc_cms__pspVariantOperation`.

**Vary the image AND the copy, then prove it.** A variation whose variant hero is the same file as the base and whose subject matches the base is wired correctly and shows the recipient nothing different. Diff the variant `src` against the base `src` (compare on the `ids=` parameter or the filename, not the escaped string) before calling it done.

Design rule: target a segment OTHER than the campaign's own audience. Targeting a campaign at its own segment matches 100 percent of the send and makes the default dead.

Other traps: changing a block's `definition` after operations are bound returns `DeleteRestrictedByFkException` and writes nothing, so restructure before attaching. A point bound to content can never be deleted, even after the content is deleted; an unbound point deletes cleanly. SMS content is flat with no blocks, so it carries no dynamic image.

## Flows, with a real Path Experiment

`POST /tooling/sobjects/Flow` `{FullName:"flow_<campaignId>_<epoch>", Metadata:{processType:"Journey", status:"Draft", start:{triggerType:"Segment", segment:"<18 char MarketSegment Id>", connector}, decisions, actionCalls, waits, experiments, exitRules}}`.

**A Journey Flow POST creates the FlowRecord automatically**; FlowRecord itself has zero createable fields. Link to the campaign with `PATCH /sobjects/FlowRecord/{2aF}` `{"AssociatedRecordId":"<701>"}`.

The Path Experiment element, verified accepted:

```json
"experiments": [{
  "name": "cld_Path_Experiment",
  "label": "A/B: <the two angles>",
  "type": "Automatic",
  "testGroupPercentage": 20,
  "duration": 2,
  "durationUnit": "Weeks",
  "fallbackMode": "BestPerformer",
  "primaryMetric": "Conversion",
  "paths": [
    {"name":"Path_A","label":"Path A","percentage":50,"connector":{"targetReference":"Send_Email_A"}},
    {"name":"Path_B","label":"Path B","percentage":50,"connector":{"targetReference":"Send_Email_B"}}
  ]
}]
```

Do not model an A/B split as a Decision. The real element exists and the API accepts it.

Other flow facts: `waits[]` need `defaultConnectorLabel`; `offsetUnit: "Hours"`; `SECOND()` needs `TIMEVALUE()`. A Tooling PATCH on a Draft Journey flow **re-issues the Flow Id**, so re-query `FlowDefinition.LatestVersionId` after every PATCH. `InvalidDraft` status is normal until From address, subscription, SMS sender code and a segment schedule are set, and is acceptable in a demo org.

## Members and mock engagement that actually renders

Apex generators, deployed with `POST /tooling/sobjects/ApexClass`. Use **Bresenham style allocation**, not modulo: a modulo cycle only hits the target rate when n is a multiple of 100 and is wrong in every real cell.

### The vocabulary that decides whether the OOTB dashboards show anything

This is the difference between a campaign that looks alive in the standard Insights and Deliverability tabs and one that shows a wall of zeros. Event types alone are not enough; two status fields decide it.

| Field | MUST be | Not |
|---|---|---|
| `ssot__EmailRecipientSendStatus__c` | `SENT`, and `NOT_SENT` on a bounce | `Sent`, `Bounced`, `Delivered` |
| `ssot__EmailBounceType__c` | `HARD_BOUNCE` / `SOFT_BOUNCE` | `Hard`, `Soft` |
| `ssot__EngagementChannelActionId__c` | `SEND`, `SEND_STATUS`, `OPEN`, `CLICK`, `BOUNCE`, `UNSUBSCRIBE` | anything partial |

Note the trap inside the trap: it is not "uppercase everything". `Bounced` becomes `NOT_SENT`, because that field describes whether the send succeeded, not what happened afterwards.

**The diagnostic signature: Click-Through Rate renders correctly while every other tile reads zero.** CTR is clicks over opens and applies no send-status filter; Sends, Open Rate, Click Rate, Delivery Rate, Bounces and Opt-Out Rate all count or divide by sends. If you see that pattern, it is the vocabulary, not missing data. Confirm by diffing your rows against a pre-existing dataset in the same org that does render.

More rules:

- **Emit the full lifecycle.** Missing `SEND` zeroes six tiles at once because it is the denominator.
- **Guarantee an EMAIL-channel floor.** At a realistic 1 to 2 percent, a 135 person audience can produce a single bounce and land it on SMS by chance, leaving every Email deliverability tile blank. Force the first recipient of each variant to bounce and the second to unsubscribe.
- **Bounces and unsubscribes must exist on the EMAIL channel specifically**; the Deliverability tab filters `ssot__EngagementChannelTypeId__c = EMAIL`.
- **Fill the whole 30 day window.** Anchor to `Datetime.now()` and spread sends across roughly now-26d to now-6d. Data at a fixed offset ages out of a Last 30 Days filter while the org sits idle.
- **Make the seed idempotent** (delete by a group field, re-insert) so it is safe to re-run, and re-run it after any idle period.
- Verify by joining `ssot__EmailEngagement__dlm` through `ssot__BulkEmailMessageId__c` to `ssot__BulkEmailMessage__dlm.ssot__CampaignId__c`; there is no campaign column on the engagement DMO. The action column is `ssot__EngagementChannelActionId__c`, not `...ActionTypeId__c`.

Plausible seeding ranges, so the out-of-the-box dashboards read as a real campaign rather than a wall of zeros: open 32 to 45 percent, click to open 12 to 18, SMS response 15 to 22, conversions 2 to 4 percent of sends. Click to open is the most stable of these across industries and the least distorted by Apple Mail Privacy Protection, so it is the one worth generating carefully. Make B beat A on most campaigns but not all. Cells under n = 60 cannot express a rate.

### Apex mechanics

**Updating a class in place** (a PATCH of `Body` fails with INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY, and deleting a class an LWC or guest site depends on is unsafe):
```
POST /tooling/sobjects/MetadataContainer   {"Name":"..."}
POST /tooling/sobjects/ApexClassMember     {MetadataContainerId, ContentEntityId, Body}
POST /tooling/sobjects/ContainerAsyncRequest {MetadataContainerId, IsCheckOnly:false}
poll ContainerAsyncRequest for State
```

Apex traps: a `+` in an `executeAnonymous` query string decodes as a space and produces a compile error pointing at the wrong token, so build output with a `List<String>` and `String.join` and never use `i++`. A `throw` in the same block rolls back all DML, so commit with a plain call and read counts in a separate throwing call. **`when` is a reserved word** and cannot be a variable name. Apex identifiers are case insensitive, so a parameter `src` shadows a constant `SRC`. DLO columns are `<field>_c__c`, CRM fields are `<field>__c`.

Data stream refresh is `POST /ssot/data-streams/{name}/actions/run` `{}`. The verb is `run`, not `refresh`.

## Campaign outcomes and goals

Before trusting a custom-built outcomes panel, read its controller. Common defects found in one: objective and conversion signal were restricted picklists with defaults, so unset campaigns displayed a confident wrong answer instead of a blank; actual counted CampaignMembers at one specific status; channel credit was derived from the campaign **name**, making the attribution model selector inert; and the "web is not connected" caveat was a hardcoded literal that checked nothing.

Derive channel touches from real engagement rows, allocate credit per model (first, last, linear, time decay with a 7 day half life, position based), and compute percent in Apex because `SUM OVER PARTITION` is unavailable in Data Cloud SQL here. Set targets from the real converted contacts so attainment lands between roughly 60 and 115 percent with variety; every campaign at exactly 100 reads as fake.

## Reporting

Per unit: a table of ids, counts against predicted counts, every error verbatim, and the human steps that remain. Write a log doc per layer to the project.

---
name: sfdc-web-affinity
description: "Stand up website behavioural data in a Salesforce demo org: a portable instrumented website, category tagging, the Web SDK and connector, DLO to DMO mapping, a category affinity Calculated Insight, an affinity wheel on the contact card, a guest write endpoint for an instant web-to-contact demo, and what it actually takes to segment on any of it. Use when asked about web engagement, affinity wheels, category tagging, web attribution, the Web SDK, personalization zones, or connecting a website to Data Cloud."
---

# Web engagement and category affinity

Built and verified 2026-09-02 in a healthcare demo org. This covers the website, the pipeline into Data Cloud, the affinity insight, the contact card component, and the limits of each.

## The chain

```
page or article tagged with one of N categories
  -> event carries the category (in the URL path and as an attribute)
  -> DLO
  -> mapped to ssot__WebsiteEngagement__dlm.engagementServiceLine__c
  -> Calculated Insight: person x category x count x last seen
  -> Apex controller -> affinity wheel LWC on the Contact page
```

Two sources feed the same DMO by design: seeded mock rows through a CRM object, and live rows through a guest endpoint or the Web connector. Everything downstream is source agnostic, which lets the whole story be built and demoed before a connector exists.

## Know what the pipeline costs before promising a demo

Measured, not estimated:

| Hop | Trigger | Time |
|---|---|---|
| Browser to CRM row | immediate | under a second |
| CRM row to Data Cloud DMO | data stream run | **5 to 11 minutes** |
| DMO to affinity CI | CI run | seconds once triggered |
| CI to wheel | page load | immediate |
| CRM Contact to unified profile | identity resolution job | **10 to 30 minutes** |

Neither middle step fires on its own. A CI on a 24 hour schedule means today's clicks surface tomorrow unless you run it. Identity resolution may have `doesRunAutomatically: false`, in which case it has not run since somebody last pressed the button. **Read `lastJobCompleted` before assuming anything is current.**

Consequence for agents: never sleep inside a run waiting for these. Fire the job, end the turn, check later.

## What needs identity resolution and what does not

This distinction decides whether a demo works, and people assume wrongly in both directions.

| Capability | Needs identity resolution |
|---|---|
| Affinity wheel and recent web engagement on the contact card | **No.** Key on email and record id directly |
| Segment membership, campaign entry, activation | **Yes.** Segments run on the unified DMO |

So a person can appear on a contact card with a full affinity wheel minutes after typing their email, and still be invisible to every segment. Say this out loud when handing the kit over; a teammate will assume the wheel appearing means the person is targetable.

And even once unified, a web-only visitor matches nothing if every segment filters on payer or patient profile attributes they do not have. Behaviour-based targeting needs a segment built on web engagement or the affinity insight, not on profile fields.

## Taxonomy first, and keep it fixed

Pick 6 to 8 categories and never vary them. They appear in the site tags, the seed, the DMO field, the CI group by, and the LWC palette; changing the list means touching all five. Fewer than about six makes a thin, unconvincing wheel.

**Every category must map to something already in the org** (a condition flag, a quality measure, a campaign), or the wheel is decorative. The point is to enable "reads diabetes content and has an open A1C gap", not a pretty chart.

## Seeding realistic affinity

The weighting matters more than the volume. Per person: a dominant category at about 45 percent of their events, a secondary at 25, the rest spread over two or three others. Event counts varied (3 to 30). Timestamps across 90 days weighted recent. Derive everything from a hash of the person id so it is reproducible rather than random.

**Derive the dominant category from the person's real profile**, first match wins: diabetes flag to a diabetes category, hypertension to cardiovascular, an open screening gap to that screening category, Medicare or 60 plus to benefits, and so on, with a small percentage overridden to a rare category so it is represented.

A uniform random seed produces a flat wheel that reads as noise. Across eight categories the flat baseline is 12.5 percent; a real preference needs to sit three to four times above it. The same applies to a live visitor: four categories at two events each draws an evenly quartered wheel that is technically correct and visually meaningless, so coach the demo to click one category repeatedly.

Idempotency: a regenerate of thousands of rows exceeds the 10,000 DML row limit, so have `run(true)` purge and ask to be called again. Two calls for a clean rebuild.

## Identity: key on email, not a record id

The single most important design decision. A live visitor is identified by **email**, not a CRM record id, so seed the mock rows with the email too. `ssot__WebsiteEngagement__dlm.ssot__AccountContactId__c` declares a relationship to `ssot__ContactPointEmail__dlm.ssot__EmailAddress__c` and beacon mappings typically write the email into both that and `ssot__IndividualId__c`. Match on both, case insensitively; `LOWER()` works in the CdpQuery dialect.

Email matching email needs no identity resolution, which is what makes a live demo possible.

Know the limits and say them out loud: browsing done **before** someone identifies themselves carries no email and never joins. That is true of every web personalization story, not a defect.

## DLO to DMO mapping contract

| Fact | Detail |
|---|---|
| List | `GET /ssot/data-model-object-mappings?dmoDeveloperName=<dmo>`. **The bare list route 404s**; the query parameter is what makes it serve |
| Item route | `GET`, `HEAD`, `DELETE` only. `PATCH` returns METHOD_NOT_ALLOWED |
| Adding a field | Delete the mapping, re-POST the full field list plus the new pair. A second POST alongside fails with `DUPLICATE_DLO_TO_DMO_MAPPING` |
| Field name mangling | A CRM field `X__c` becomes `X_c__c` in the mapping body |

Refresh a stream with `POST /ssot/data-streams/{name}/actions/run` and an empty body. The verb is `run`, not `refresh`; `refresh` 404s.

One DLO can map into more than one DMO. If a web mapping reuses a field that an email mapping also uses (for example a send-status field carrying `utm_medium` for the web rows), never bulk-rewrite that field without excluding the web rows by channel.

## Calculated Insight contract

| Step | Call |
|---|---|
| Create | `POST /ssot/calculated-insights` with exactly `apiName`, `displayName`, `definitionType: "CALCULATED_METRIC"`, `publishScheduleInterval`, `publishScheduleStartDateTime`, `expression`. Do NOT send `dimensions`, `measures` or `dataSpace`; they are derived and the create fails |
| Interval value | `"TWENTYFOUR"`, echoed back as `TWENTY_FOUR`. `DAILY`, `Daily`, `DAY` and `Days` are all rejected |
| Run now | `POST /ssot/calculated-insights/{apiName}/actions/run` `{}` |
| Read | `GET /ssot/calculated-insights/{apiName}`. The `-definitions` path and `/runs` are 404s. Query its output at `{apiName}`, not `{apiName}__dlm` |

**Validate the SQL on queryv2 first**, but know the limit: queryv2 and the CI engine are different dialects. `DATE_SUB` exists in the CI dialect and fails on queryv2. So queryv2 validates grain, joins and aggregation only.

**Dimensions are frozen at create.** Measures and the expression patch freely; changing a dimension means delete and re-POST. Decide the grain first, and when in doubt include both candidate person keys as dimensions so the CI does not go blind when the live key differs from the seeded one. Note that a CI dimensioned on email and a CRM record id does not automatically join to the unified individual, which is the entity segmentation runs on.

## The wheel component

Apex controller plus an inline SVG donut LWC on the Contact page. Rules that matter:

- Compute percent in **Apex**, never in Data Cloud SQL (`SUM OVER PARTITION` is unavailable).
- Restrict to the known category list. The DMO field is polluted beyond null: real values include `SMS`, `WEB` and stray record ids, so filtering with `<> ''` grows junk categories.
- Always return every category, so a partial ring still draws a complete circle, and return an explicit empty flag rather than a broken wheel for people with no browsing.
- Read Data Cloud first, fall back to CRM SOQL both on exception **and on zero usable rows**, and say which path ran in a `dataSource` string. Given the 5 to 11 minute ingestion lag, the CRM fallback is what makes a live demo work at all; consider making it the primary path for records carrying the live-visitor marker.
- Use a categorical palette that cannot be confused with semantic red, amber and green used for compliance status elsewhere.

LWC bundle traps: a POST rejects a supplied `.js-meta.xml` as auto generated, and `targetConfigs` as raw XML triggers a misleading `AURA_COMPILE_ERROR` about a missing label. Send only html, js and css, and put `masterLabel`, `isExposed`, `apiVersion` and `targets` in the bundle metadata.

## Portable website

Remix rather than rebuild. Regenerating a site from a prompt produces different markup, and the sitemap binds to `data-event` attributes and path patterns, so a rebuild means re-deriving every rule.

Strip the personalization theater but **keep the identity plumbing**: the hidden admin identity page, every `data-event` attribute, the sitemap and schema, and the category tags. Removing the identity switcher kills affinity entirely.

One value cannot be copied: the beacon GUID is per connector. Put it, and any endpoint URL, in **one config file** so a teammate changes one file.

No credentials are needed anywhere. The beacon GUID is a public identifier in a CDN URL, and a Salesforce Site guest user serves anonymous traffic. If a website project asks for OAuth client secrets, something is architecturally wrong; remove it.

**Check that capture actually fires on the action the user takes.** A common and invisible failure: the handoff is called from a page-view handler, while every form submit sets local state and shows an inline success message without changing route. The forms then capture an email that never leaves the browser, and the only thing that ever posts is a later navigation. Test one form end to end and count the records; do not read the code and assume.

**Attributes are not wiring.** `data-event` attributes on buttons document intent. Unless the SDK reads them or an onClick calls the tracker, they do nothing. Check which.

**A remix call that times out has usually still succeeded.** Re-sending creates a duplicate project and burns credits; check the project list before retrying.

## The instant demo path, and the bug that will bite you

Real beacon events take minutes to reach Data Cloud, which kills a three minute demo. For the demo moment only, a guest accessible Apex REST endpoint on a Salesforce Site can take an email plus the session's browsing history, find or create a Contact, and write engagement rows directly, so the wheel paints in seconds.

**The Guest User cannot SEE Contact records under `with sharing`.** A class declared `global with sharing` runs its match query, gets zero rows every single time, and inserts a NEW Contact on every call. Eight page views produce eight duplicate contacts each holding one event, so no record ever has enough history to draw a wheel. The symptom looks like a broken affinity pipeline rather than a sharing problem, which is what makes it expensive.

Fix: put the lookup and insert in a private `without sharing` inner class, scoped as narrowly as possible, one exact-email query and one insert. Also give every event a stable id key and skip keys already stored, so a resent visit log cannot inflate the affinity.

This is a **demo only pattern, never production**. Guard it: a shared token in the body (not a secret, it ships in client JavaScript, so say so in the code), an allowlist of categories, a cap on events per call, write only with no data returned beyond the record id, and a marker field on everything created so it is deletable. Gate any created-versus-matched response behind the token or the endpoint becomes an email enumeration oracle.

Guest access needs: an Apex class grant, object create and field permissions on a permission set assigned to the site guest user (all API writable), and a `CorsWhitelistEntry` for the site origin. **Guest reachability can only be proven from a browser**; an authenticated call proves nothing.

## Before claiming a site is connected to Data Cloud

Check both halves and report which exist:

- **Site:** an SDK script tag in `index.html`, an init call, and a real beacon GUID. A `BEACON_GUID` constant whose value is the literal string `BEACON_GUID`, imported by nothing, is a placeholder.
- **Org:** a Web and Mobile App connector among the data connections, and an uploaded schema.

A site that console-logs, dispatches a `CustomEvent` and writes `localStorage` is an event-log demo, not an SDK integration, and it captures nothing anonymously. Calling that "web affinity is set up" when the affinity is entirely seeded plus one guest endpoint is the kind of claim that falls apart in front of a customer.

---
name: tableau-next-dashboard-craft
description: "Build, style and embed Tableau Next (Salesforce) dashboards, visualizations, metrics and semantic models over the REST API in any demo or customer org, with the eye of a data-viz engineer and the discipline of a technical PM. Use whenever someone mentions Tableau Next, Tableau Einstein, Data 360 analytics dashboards, semantic models, metric tiles, \"Can't show visualization\", embedding analytics in a Lightning page, or wants a dashboard that looks designed (goal lines, colour by category, title cards, section bands) rather than a default grid of charts."
---

# Tableau Next dashboard craft

You are acting as a technical product manager who used to be a data-viz engineer and still cares how a dashboard feels in the hand. Two beliefs drive everything below. First, the REST API is the real authoring surface: a dashboard generated from a script is reproducible, reviewable and portable across orgs, and the UI is for discovering shapes you cannot guess. Second, a dashboard is an argument, not an inventory. Every chart title states a finding, every section answers a question, every colour means one thing.

This skill was distilled from ~35 build passes in a healthcare payer demo org (membership, population health) between Aug 29 and Sep 1 2026. Grades used throughout: **[org]** executed live; **[doc]** Salesforce Help; **[gap]** tried and rejected or never found. Do not promise a prospect anything marked [gap].

The full reference set (exact JSON contracts, design system, every gotcha, learning links, and Python generators) lives in the packaged skill folder `tableau-next-dashboard-craft/` (references/api-contract.md, references/design-system.md, references/gotchas-and-challenges.md, references/learning-links.md, scripts/), which is not included in this public pack. When those files are available, read the matching one before building. When they are not, the essentials are below.

## The workflow that works

### 0. Get the org facts first

1. Confirm Tableau Next Creator/Consumer permission set licenses are Active.
2. `GET /services/data/v67.0/tableau/workspaces` and `GET /services/data/v67.0/ssot/semantic/models`.
3. **List existing instances of whatever you are about to create** (`GET /services/data/v66.0/tableau/visualizations`, `/services/data/v67.0/tableau/dashboards`) and read one complete body. OOTB dashboards (Campaign Insights, Consumption Analytics, Marketing Performance) are the schema documentation the API does not give you. This habit cracked every blocker we hit.
4. Note the semantic model id (`2SM…`), workspace id (`1Dy…`), and the semantic **object** apiName (e.g. `PayerProfile`), which is not the DMO name.

### 1. Build bottom-up: semantic model → metrics → vizzes → dashboard → embed

- **Semantic model**: `POST /ssot/semantic/models`, then `data-objects` with `dataObjectType: "Dmo"` and `shouldIncludeAllFields: true`. Relationships use `joinType: "Auto"` and semantic field api names (digit-suffixed on collision). Calculated Insights cannot be added as data objects [gap].
- **Metrics** `POST …/models/{model}/metrics`: `aggregationType` is `Average`/`Sum`/`Count` (not `Avg`), `timeDimensionReference` required in practice, `additionalDimensions` must include every field a dashboard filter uses or the filter silently ignores the tile. PUT/DELETE only, no PATCH.
- **Visualizations** `POST /services/data/v66.0/tableau/visualizations`: v66.0, because `marks`/`rows`/`columns`/`style` cap at API 66.07 (the "not allowed for API version 67.0" error is a version window, not a permission gate). Use `viewSpecification.filters` (plural). Viz `function` is `Avg`. Label ≤ 80 chars. `style.fit: "Entire"` on every dashboard viz. `style.axis[key]` for every continuous field. PATCH is a full replace.
- **Dashboards** `POST/PATCH /services/data/v67.0/tableau/dashboards`: `workspaceIdOrApiName` is the field that unblocks create (the "ask your admin" message is a missing workspace). PATCH is a full replace: send `label`, `name`, `workspaceIdOrApiName`, `layouts`, `widgets` every time. Widget `source` on input is `{id, name}` only. Response carries `status: Ok` per widget; read it.
- **Embed**: Lightning App Builder Tableau Next Dashboard component, or Tooling API FlexiPage component `analytics_embedding:dashboard` with `dashboardId` = api name, `height`, `hideTitle true`, `navigationMode Inline`. Height ≈ rows × rowHeight + gaps + 60.

### 2. Render-breaking rules

1. A reference line needs both halves: `visualSpecification.referenceLines[key] = ["Line", {"type":"Line","fieldKey":"F2","scope":"Table","line":{"valueType":"Value","value":0.75,"label":{"type":"Custom","labelText":"Goal 75%"}}}]` AND `style.referenceLines[key] = {"isVisible":true,"lineFormat":{"color":"#B91C1C","type":"Solid"},"labelAlignment":{"vertical":"Top","horizontal":"Right"}}`. Spec alone returns 200 and renders "Can't show visualization". Read-back drops the wrapper array; restore it before the next PATCH. `Dashed` is rejected.
2. A Color encoding (`marks.ALL.encodings: [{"fieldKey":"F3","type":"Color"}]`) needs `legends.F3` with a `position`, `style.marks.ALL.color.color: ""`, and F3 absent from `allHeaders.fields`. Auto palette only; per-category colour maps, gradients, `Funnel`, `Pie` are [gap] over REST. Build in the UI, GET, copy.
3. Crosstab needs `style.axis[<MeasureValues key>]`.
4. Dashboard `maxWidth` wider than the Lightning region makes the whole canvas blurry (CSS-scaled). 1000–1150 for a full-width app page.
5. Viz label does not render on the dashboard; the row field label does. Hide it (`style.fieldLabels.rows.showLabels: false`) and use a text title card.

### 3. Design pass (where the wow comes from)

- Grid: 72 columns, `rowHeight 12`, `cellSpacingX/Y 8`. Filters 11 cols × 5 rows, brand block 17 cols × 5 rows (15px bold + 12px subtitle), divider rule 1 row, hero 8 rows, section bands 3 rows, title cards 6 rows, charts 18 rows, tiles 24 rows, tables 40. Halves and full width only; thirds clip a 13px sentence.
- Hero: one sentence with the number in it (20px bold `#2E1065` on `#EDE9FE`) plus what to do about it (13px `#5B21B6`).
- Section band: `#E8EAF0`, 4px left border in the family colour, 12px caps label.
- Title card above every chart: 13px bold ink `#042339` takeaway + 11px muted `#5A6B7B` subtitle (denominators, time frame, caveats), tinted family background, 2px family bottom rule, radius 8; chart below white with left/right/bottom `#E5E5E5` border so the pair reads as one card.
- One colour family per meaning: blue `#1D4ED8` cost, teal `#0F766E` membership/brand, purple `#6D28D9` clinical, amber `#B45309` retention, green `#15803D` quality, red `#B91C1C` goal lines and utilization pressure, slate `#5A6B7B` neutral. Tints: `#EFF6FF #F0FDFA #F5F3FF #FFFBEB #F0FDF4 #FEF2F2 #F1F5F9`.
- Metric tiles: white, 4px top border in the family colour; `insights` on for at most two headline tiles.
- Goal bars = horizontal bar + red labelled reference line. This replaces gauges and bullet graphs.
- Titles state findings with the number in them; rates over counts when cohorts differ; denominators and thin cells (n<30) in the subtitle; say "placeholder" when a goal is one.

### 4. Verify live, then write it down

PATCH → read per-widget `status` → reload the embedded page → screenshot. A 200 proves the parser accepted it, not that it renders. Log ids, accepted and rejected values. Call out anything added unasked. When an unknown shape survives three error-walk attempts, stop and build one in the UI, GET it, copy it.

## Still open (Sep 2026)

Per-category colour mapping, gradient shading, Funnel and heat-map marks, dynamic text bound to metrics, measure filters, viz-level calcs, metric value formatting (0.77 vs 77%), Flow actions, Summary/Parameter/Image widget REST shapes. All exist in the UI; REST shapes are [gap].

## Learning links

Help hub: https://help.salesforce.com/s/articleView?id=analytics.tua_create.htm · Dashboards: https://help.salesforce.com/s/articleView?id=analytics.tua_create_dashboard.htm · Reference lines: https://help.salesforce.com/s/articleView?id=analytics.tua_create_viz_reference_line_about.htm · REST API: https://developer.salesforce.com/docs/analytics/tableau-next-rest-api/overview · Semantics APIs: https://developer.salesforce.com/docs/data/semantic-layer/guide/get-started.html · Embedding SDK: https://developer.salesforce.com/docs/analytics/sdk/guide/sdk-overview.html · Trailhead trail: https://trailhead.salesforce.com/content/learn/trails/unlock-actionable-data-insights-with-tableau-next · Craft: https://www.vizwiz.com/2018/07/visual-vocabulary.html, https://www.storytellingwithdata.com/blog/2020/3/5/transforming-slide-titles, https://www.perceptualedge.com/articles/misc/Bullet_Graph_Design_Spec.pdf