forcedotcom/sf-skills / skills/platform-dsar-policy-manage
platform-dsar-policy-manage
VerifiedSet up, edit, run, and audit a customer's personal-data portability map (DsarPolicy / Right-to-Portability export). Use for choosing subject roots, follow/stop relationships and fields, including requests to figure out what counts as personal data: elicit the admin's classification decisions, never guess. Covers inactive policy authoring/review, subject resolution, ACTIVE-policy export with bounded polling and terminal-only download, history and coverage gaps. This end-to-end workflow can dispatch the DsarPolicyManager setup SOR; loading its generated configuration skill alone does not replace this workflow. Not subject erasure/deletion, sandbox masking or unrelated metadata deployment.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 20.5 KB |
| references/configure.md | markdown | 4.4 KB |
| references/export-and-history.md | markdown | 5.8 KB |
| references/gap-analysis-guide.md | markdown | 9.5 KB |
| references/gap-scan.md | markdown | 8.0 KB |
| references/headless-sor.md | markdown | 3.0 KB |
| references/report-format.md | markdown | 4.2 KB |
| scripts/tests/__init__.py | script | 0 B |
| scripts/tests/test_validate_policy_tree.py | script | 2.6 KB |
| scripts/validate-policy-tree.pyexecutable | script | 3.9 KB |
SKILL.md
View on GitHub---
name: platform-dsar-policy-manage
description: "Set up, edit, run, and audit a customer's personal-data portability map (DsarPolicy / Right-to-Portability export). Use for choosing subject roots, follow/stop relationships and fields, including requests to figure out what counts as personal data: elicit the admin's classification decisions, never guess. Covers inactive policy authoring/review, subject resolution, ACTIVE-policy export with bounded polling and terminal-only download, history and coverage gaps. This end-to-end workflow can dispatch the DsarPolicyManager setup SOR; loading its generated configuration skill alone does not replace this workflow. Not subject erasure/deletion, sandbox masking or unrelated metadata deployment."
metadata:
version: "1.7"
domains: ["Platform"]
minApiVersion: "68.0"
cliTools:
- tool: ["python3"]
semver: ">=3.10.0"
- tool: ["sf"]
semver: ">=2.0.0"
---
# platform-dsar-policy-manage: DsarPolicy Right to Portability, end to end
Operate a **`DsarPolicy`** — the metadata driving a **Right-to-Portability (RTP)** export — across
its lifecycle: **configure** the tree, **run** an export, **audit** runs. A `DsarPolicy` is a
*read/export map*: it names which of a subject's records an export collects. It **never deletes
anything**. The value here is **judgment**, not XML plumbing.
> **FIRST LINE OF EVERY RESPONSE — do not narrate the skill.** Your first output token is *work or
> the answer*, never a play-by-play. Do **not** open with "This is a coverage-gap audit / Workflow
> D…", "Let me read the skill's guide/mechanics…", "Per rule #1…", or "Let me discover the SOR…".
> Don't name the workflow, announce which reference files you're about to read, or describe your
> method before doing it — just start doing it (call the tool) and, when done, present the result.
> This is load-bearing call #8, stated up front because it governs your very first token. A
> plain-language sentence about *the user's data/org* is fine; a sentence about *the skill, its
> workflows, rules, tools, or files* is not.
## Load-bearing calls (get these right or the task fails)
These override any leading phrasing in the request. Read them first, every time. **Call #1 is the
literal first action of every task — before you pick a workflow, before any `sf` command.**
1. **Route through the SOR tool FIRST — before any `sf`/endpoint call, no exceptions.** The very
first action of *every* task here — including a trivial read-only "does a policy exist / list the
policies" lookup — is to scan **this run's available tools** for a capability-routing tool exposing
**discover / describe / dispatch** verbs (project-codey / Headless 360 today; any host prefix such
as `mcp__<host>__discover`; **match the verb shape, not a fixed name**). If one is present, that is
the entry move: `discover → describe → dispatch` the **`DsarPolicyManager`** SOR (owner Privacy
Center; `isActive` gates execute/edit/delete) and reject look-alikes (data mask, generic consent,
subject *erasure*). Do **not** reach for `sf` first — grabbing `sf` on reflex because the task
"looks like a quick lookup" is the top recurring miss, and it is wrong even when it would work.
`sf` is the fallback **only** when no routing tool is in reach (checking `sf org list` to see which
orgs are authenticated locally is fine — that is a client-side auth check, not a SOR call). Every
`sf` command shown in the workflows below is the *no-routing-tool*
spelling; when the routing tool is present, dispatch the equivalent operation through it instead.
Detail: `references/headless-sor.md`.
2. **Export, never erasure.** A run produces an **export file**; it does not erase/redact/delete the
subject. If the request frames it as deletion ("remove them", "erase", "clear out"), **correct
that first** and never report the subject as erased. Erasure is a separate mechanism — if that's
the goal, say so and stop. You may still export if authorization is clear, after correcting the
premise.
3. **Do not guess personal data.** Which objects/relationships hold *the subject's* data is the
**admin's** classification call. If the request delegates it ("figure out what counts", "wire the
whole thing up"), **do not author a guessed tree** — enumerate the decisions the admin must make
(roots; per-relationship follow/stop; fields), mark any proposal *pending admin disposition*. An
over-broad guess exports other people's records.
4. **Caps are hard — name the cap and stop; don't graph-walk.** Tree caps: **10 children/path, depth
10, 200 nodes**. An unbounded request ("everything", "the whole graph") cannot fit. Do **not**
enumerate the object graph to "try" (never finishes, burns the turn). Name the specific cap
exceeded and offer a bounded alternative (split policies, prune branches). Never silently truncate.
5. **Poll a couple of times, then ask — don't block on terminal.** The run handle serves status
**and** file. An early *getfile* returns `NOT_FOUND` / `"This file isn't ready yet"` — the
contract working, not a failure. Poll ≈2–3×; if still not terminal, **stop and ask the user
whether to keep polling** — don't loop. A run can sit non-terminal indefinitely on downstream
async processing — **platform / Tool Factory territory, not this skill's to diagnose or reach
into**; report status in plain terms (**running / completed / errored**) and let the user decide.
Never download before terminal. A **failed run can return HTTP 201** — read the **envelope /
`RequestStatus`** in the body, not the HTTP code. getfile segment is **`dsr`**, not `dsar`.
6. **History is a read.** Run history = a **SOQL query over `DsarPolicyLog`**. Not `installListView`,
not a UI list; it starts no run.
7. **Never auto-activate or republish.** Activation is a deliberate, human-confirmed step. Editing an
ACTIVE policy needs it deactivated first — **deactivate → edit → stop, report, get explicit user
confirmation before reactivating**. New policies stay INACTIVE until the user activates.
Auto-republishing breaks the reviewable audit trail disputes depend on.
8. **Work silently — never narrate the skill's internals (applies to every workflow; see the
masthead above).** The user asked a domain question; answer it, don't describe how the skill
answers it. Run the tools and present the result — **no intermediate narration** of: that you are
about to read / are reading the skill's guide, mechanics, or reference files ("let me read the
skill's guide and mechanics"); **which workflow this is** ("this is a coverage-gap audit / Workflow
D", "Workflow C-style read") — the user does not think in workflow letters, so never name one;
which SOR/routing tool you're using or that you're "loading schemas / discovering / dispatching";
the load-bearing rule numbers ("per rule #1"); the reject-look-alikes step; the operation graph or
GET-vs-dispatch plumbing (`getAccessInfo`, `dispatch_readonly`, etc.). These steer *how you work* —
they are not status updates. (The harness still shows its own plain tool-call lines; that is fine —
just don't add your own play-by-play.) **What the user DOES see:** the final answer, and — where a
call requires it — a plain-language question (`AskUserQuestion`) or a short scope/consent line about
*their org* ("I only listed policies; I changed nothing", "this exports, it doesn't delete"). Rule
of thumb: a sentence about **their data/org** can be user-facing; a sentence about **the skill, its
workflows, steps, tools, rules, or files** stays internal. Workflow D's method preamble is the one
allowed "here's how I'll do it" line, and even it must be plain-language about *the audit approach*
("I'll look one level out from your policy's objects and flag fields that might hold personal
data") — it names **no** workflow letter, rule, tool, or file. That preamble is *not* a licence to
say "this is Workflow D" or "let me read the mechanics".
## The DsarPolicy object model
Each entity is reached a **different** way — guessing the surface is the top time-sink.
| Entity | What it is | How you reach it |
|--------|-----------|------------------|
| `DsarPolicy` | Policy shell + lifecycle (ACTIVE/INACTIVE) | **Metadata API** |
| `DsarPolicyPath` | A tree node: a root object, or a parent→related relationship | **Metadata API** (child of `DsarPolicy`) |
| `DsarPolicyField` | A field collected at a path | **Metadata API** (child of a path) |
| `DsarPolicyLog` | Run log (one row per run) | **Standard SOQL** |
| Execute an export | — | **Connect DSR endpoint** (`POST`) |
| Status / getfile | — | **Connect DSR endpoint** on the handle; getfile segment `dsr` |
Resolve the exact Connect route through the routing tool's `describe`; only when no router is available,
use the verified-contract/`sf` fallback in `references/export-and-history.md`. Don't
`sf sobject describe DsarPolicy*` — the tree is metadata; only `DsarPolicyLog` answers standard
SOQL. On an MCP surface, each row is one `DsarPolicyManager` operation.
## Pick the workflow (by the verb)
| Want to… | Run | Ends when |
|---|---|---|
| Set up / edit a policy tree | **A — Configure** | Bounded policy authored INACTIVE; or an unbounded request's cap is named / an under-specified one's decisions enumerated — and stops |
| Run an export for a subject | **B — Export** | Subject resolved to a root Id, run status read (running/completed/errored), file located on success — or, if still running after a couple polls, the user is asked whether to continue |
| See past runs | **C — History** | Prior runs reported from `DsarPolicyLog`, no run started |
| Find PII not yet covered | **D — Coverage gap** | Candidates surfaced with per-field reasons, disposition left to the admin — read-only |
Mixed request → do the one asked; don't add an export to a configure, or a run to a history.
**Every workflow below assumes call #1 is already done** — you have routed through the discover/
describe/dispatch SOR tool (or confirmed none is in reach). The `sf`
commands in each workflow are the *no-routing-tool* spelling; with the routing tool present, dispatch
the equivalent operation through it.
## Workflow A — Configure
Recipe (metadata shape, relationship/field resolution, lifecycle transitions): `references/configure.md`.
1. **Classify first — short-circuit before any describe.** Three shapes; two never reach authoring:
- **Unbounded** ("everything", "whole graph") — can't fit caps. Don't describe/walk. Write the
**cap-refusal report** (call #3), stop.
- **Under-specified** — delegates classification, no root/field named. Don't author a guess.
Write the **elicitation report** (the admin's decisions; support **multiple roots**; proposals
*pending disposition*), stop.
- **Bounded & specified** — named roots/relationships/fields fitting the caps → continue.
2. **Confirm type + describe named objects only** (don't assume names, don't expand beyond what's named):
```bash
sf org list metadata --metadata-type DsarPolicy --target-org <alias> --json
sf sobject describe --sobject <NamedObject> --target-org <alias> --json
```
If `DsarPolicy` can't be listed/described, surface it and stop (accepted terminal outcome).
3. **Validate the tree** (don't eyeball caps/names):
```bash
python3 scripts/validate-policy-tree.py <tree.json>
```
Checks children≤10, depth≤10, nodes≤200, and devname `[a-zA-Z]+[a-zA-Z0-9_]*`.
4. **Author metadata INACTIVE** under `${outputDir}`, faithful to the sanctioned strategy — add no
unapproved path, drop none approved.
> **Lifecycle gate:** INACTIVE to edit/delete, ACTIVE to execute. Change an ACTIVE policy by
> **deactivate → edit → STOP**; get explicit user confirmation before reactivating (call #7).
5. **Deploy (best effort):** `sf project deploy start --source-dir <outputDir> --target-org <alias> --json`.
Deploy may fail where the type isn't fully enabled — surface the raw error + prerequisite; don't
fake success. The classification work is valid regardless.
6. **Report** the outcome reached — **cap-refusal** / **elicitation** / **authored** — per
`references/report-format.md`. Never a truncated tree called "complete".
## Workflow B — Run an export
Endpoints, sample envelopes, poll/download sequence: `references/export-and-history.md`.
- **B0. Resolve the subject.** Requests arrive as **email / name / id**, not a `dataSubjectId`.
Resolve to the **Id of a record whose type is a ROOT** of the chosen policy (Account / Contact /
Individual / Lead / User) — e.g. SOQL `Lead`/`Contact` by `Email`. Confirm the type **is a policy
root** (execute matches only the root subtree of the subject's type — a non-root subject exports
nothing). On **0 / many / non-root** matches, stop and report; never execute a guessed Id.
- **B1. Preconditions.** Policy must be **ACTIVE** (else route to A). Resolve DSR routes through
the router's `describe`, or the verified-contract fallback in `references/export-and-history.md` when no router is available.
- **Pick the policy deliberately:** named → use it; else the in-context policy; if none is
established or **multiple ACTIVE could match**, **ask to confirm** (e.g. *"Run `<policy>` for
`<subject>` — confirm?"*). Never pick silently.
- **Access:** on `401`/`403`, name the guard and stop — user perm `Consent.CAN_EXECUTE_DSAR_POLICY`,
org feature `Consent.hasDsarPortability`. State the poll-then-download ordering even on this
error path (accepted terminal outcome; don't retry blindly).
- **B2. Consent gate + correct deletion framing (call #2).** If framed as deletion, correct it first
(export, not erasure). If authorization is ambiguous, **ask** via `AskUserQuestion`; clear
authorization → proceed.
- **B3. Execute — trust the envelope, not the HTTP code.** POST execute, capture the **run handle**.
A failed run can return **HTTP 201** — read the envelope status; report failure if it says so.
- **B4. Poll ≈2–3×, then ask; download only after terminal (call #5).** Poll the handle (or
`DsarPolicyLog.RequestStatus`). Early `NOT_FOUND` / "not ready" is expected. Still not terminal
after a couple polls → **stop and ask** whether to keep polling; don't loop (non-terminal =
downstream async, not this skill's to diagnose). Report **running / completed / errored**.
- **B5. Download (terminal-success only) — segment `dsr`.** A `dsar` segment 404s. Report where the
export landed.
- **B6. Report** per `references/report-format.md`: resolved subject (id + type) and policy chosen
(+ that you asked if ambiguous); consent confirmed; **export not deletion**; outcome from the
envelope / run status in plain terms; file location on success; poll ordering explicit (couple of
polls, file only after terminal, asked if still running). State the ordering even if preconditions
blocked the run.
## Workflow C — History (a read)
```bash
sf data query --target-org <alias> \
--query "SELECT Id, DsarPolicyId, RequestStatus, CreatedDate FROM DsarPolicyLog WHERE DsarPolicyId = '<POLICY_ID>' ORDER BY CreatedDate DESC"
```
Report prior runs (when, status); "no prior runs" is valid. On absent log / `401`/`403`/`404`,
surface the raw error + prerequisite. Don't execute the policy; don't use `installListView` / a UI list.
## Workflow D — Coverage gap analysis (read-only audit)
*"What personal data isn't covered yet?"* Read-only, deterministic — surfaces **candidates** for the
admin; classifies nothing, adds/activates nothing. Script + rubric: `references/gap-analysis-guide.md`;
mechanics: `references/gap-scan.md`.
1. **Open with the plain-language method line (call #8)** — one sentence in the user's terms: from
the policy's objects, look **one level** out and flag fields that *may* be PII, **with a reason
each**; the admin decides. Do **not** say "Workflow D", "coverage-gap audit", or "let me read the
mechanics" — just state the approach in plain words and start.
2. **Read current coverage** (read-only) — gaps are relative to it.
3. **Scan one hop only, and cap the breadth** — describe each root + **at most ~5** of its
most privacy-relevant one-hop objects; depth-1 default, don't recurse. **Never read a raw
`--json` describe into the turn** — a full describe is ~100KB and the accumulated payloads
overflow the event stream, truncating the run before it writes the report (the top failure here).
Project every describe to `{name,type,label}` first (see `references/gap-scan.md`). If the
policy/type can't be read (feature off — the accepted env path), **stop at a single projected
root describe**; don't fan out. Write the report from the root + a couple of one-hop describes,
name the objects you skipped, offer them via the depth gate. **The written report is the
deliverable — draft it early and write it; don't gather everything first.**
4. **Flag candidates with a per-field reason** — compliance metadata > field type > name semantics.
Never "this *is* PII" (call #3).
5. **Report transparently** — objects scanned, each candidate + reason, covered vs newly surfaced,
and the **one-level limit** stated (even when empty).
6. **Gate depth** — go deeper only on explicit confirmation (warn: large output, heavy cost).
7. **Disposition, don't mutate** — ask which to add; adding routes to Workflow A (INACTIVE, stops for
confirmation before reactivating — call #7).
## Quick rules & gotchas
| Situation | Do |
|---|---|
| **Starting ANY task (even a trivial "list/does-a-policy-exist" read)** | **FIRST** scan this run's tools for a discover/describe/dispatch routing tool (project-codey/Headless 360; any `mcp__<host>__…` name — match the verb shape). Present → `discover`/`describe`/`dispatch` the `DsarPolicyManager` SOR. Do NOT open with `sf` on reflex. `sf` only when no routing tool is in reach (`sf org list` for local auth is exempt) |
| "Capture everything / whole graph" | Exceeds caps (10/10/200) — name the cap, offer split/prune; don't walk the graph |
| "What PII are we missing?" | Workflow D — read-only depth-1; candidates + reason; disposition to admin; add/activate nothing |
| Subject given by email/name, no Id | Resolve first (B0): query the policy's root entities; confirm a root type; 0 / many / non-root → stop |
| Multiple ACTIVE policies could match | Confirm which with the user before running — never silent |
| Run stuck `In Progress` after a couple polls | Downstream async (Tool Factory / platform), not the skill's to diagnose — report *still running*, ask whether to keep polling; don't loop |
| getfile "not ready" / `NOT_FOUND` | Expected pre-terminal — poll again; not a failure |
| HTTP 201 on execute | Not success — read the envelope status |
| getfile 404 | Segment must be `dsr`, not `dsar` |
| Just edited an ACTIVE policy | Don't auto-reactivate — stop, report, get explicit confirmation (call #6) |
| `sf sobject describe DsarPolicy` empty | Tree is Metadata-API; only `DsarPolicyLog` answers SOQL |
| `DsarPolicy` type absent | Surface + stop; don't fabricate |
| `401`/`403`/`404` or missing type | Name the prerequisite and stop; no blind retries |
## Output (write to `${outputDir}/report.md`)
Report only the workflow you ran; each command once; the key result in the first screenful.
**Be concise** — state each load-bearing point (poll ordering, export-not-deletion, the
one-level limit) **once**, not restated across an intro, an aside, and a next-steps list; keep it
well under ~150 lines and don't paste exhaustive per-object dumps. On a preflight-error path (feature
/ policy / subject absent), name the blocker + prerequisite, state the ordering once, and stop —
short. Per-workflow contracts (incl. the INACTIVE / confirmed-reactivation lifecycle and the poll
ordering): `references/report-format.md`.
## Reference index
| File | When |
|---|---|
| `references/headless-sor.md` | MCP surface: discover→describe→dispatch the SOR, reject look-alikes, `sf` fallback |
| `references/configure.md` | Metadata shape, root/relationship resolution, `<tree.json>` input, lifecycle, multi-root |
| `references/export-and-history.md` | DSR execute/status/getfile routes, envelopes, poll sequence, `dsr` segment, history query |
| `references/report-format.md` | Per-workflow report contracts |
| `references/gap-analysis-guide.md` | Workflow D: audit script, steps, candidate-flagging rubric |
| `references/gap-scan.md` | Workflow D mechanics: one-hop enumeration, diff, depth gate, report shape |
| `scripts/validate-policy-tree.py` | Deterministic cap + devname check before authoring |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |