platform-datamask-run: Salesforce Data Mask End-to-End Operation
Use this skill to operate the Salesforce Data Mask feature on a sandbox: configure a
masking policy over PII fields, start a masking job, poll it to a terminal state, report which
records were masked, and abort a run that is still in progress.
Data Mask is
sandbox-only — the run/abort REST endpoints return
on production (a runtime
sandbox guard). Confirm the target org is a sandbox before starting.
When This Skill Owns the Task
- Running a Data Mask job against a configured policy
- Polling masking-job status to completion
- Reporting masked-record counts / per-object results
- Aborting (canceling) an in-progress masking run
- Creating or identifying the policy the job runs against
Delegate elsewhere when the user is:
- hand-writing anonymization Apex →
- seeding or generating test data →
- deploying unrelated metadata →
The One Thing to Get Right First: the API surface map
The single biggest failure mode is assuming Data Mask entities are ordinary data-API objects.
They are not, and the surface differs per entity. Memorize this table before running anything —
guessing here is what turns a 3-second job into a 30-minute dead end.
| Entity | What it is | How you reach it |
|---|
| The masking policy shell (config) | Tooling API or Metadata API (thin shell: // only) — NOT standard SOQL/ |
| An object targeted by a policy (holds the optional row filter) | Tooling API only — query AND insert; row-subset "sample" runs set + here (no on the policy) |
| A field + its masking treatment | Tooling API only — query AND insert; treatment cols are + |
| The job (one masking run) | Standard SOQL — works |
| Per-object job detail (child, FK ) | Standard SOQL |
| Start a run | — | REST run API POST /services/data/v67.0/platform/data-resilience/data-mask/policies/{policyId}/run
|
| Abort a run | — | REST run API POST /services/data/v67.0/platform/data-resilience/data-mask/jobs/{jobRunId}/abort
|
Concretely:
sf sobject describe --sobject DataMaskPolicy
SELECT ... FROM DataMaskPolicy
- Query the policy via Tooling:
sf data query --use-tooling-api --query "SELECT Id, MasterLabel FROM DataMaskPolicy"
- Query the job / job-detail via standard API:
sf data query --query "SELECT Id, Status FROM DataMaskPolicyJobRun"
Full command reference:
references/api-surface.md
.
Pick the workflow that matches the request
This skill has two distinct workflows. Select ONE up front from what the user asked for, then
run every step of that workflow — neither has optional steps:
| The user wants to… | Run | Ends when |
|---|
| Configure/edit a policy and mask records; report how many were masked | Workflow A — Mask & report (below) | The masked count is reported from the detail rows |
| Cancel / abort a masking run | Workflow B — Cancel a run (further below) | The job's status is confirmed |
Choose by the verb in the request. "Create/edit a policy and run it", "mask the PII", "how many
records were masked" → Workflow A only. "Abort", "cancel", "stop the run" → Workflow B. A
mask-and-report request does not include an abort: do not start a second job to "demonstrate"
cancelling — an unrequested run wastes a full ~5–10 min job (see the pool floor in A4) and is the top
cause of this task running out of turn before it finishes the masked count it was asked for.
Workflow A — Mask & report
A1. Confirm sandbox + capture org context
Verify the org is a sandbox and grab the instance URL + a session token for the run-API calls:
bash
sf org display --target-org <alias> --json
A2. Identify or create the policy
Prefer reusing an existing policy (fastest, no deploy):
bash
sf data query --use-tooling-api --target-org <alias> \
--query "SELECT Id, DeveloperName, MasterLabel FROM DataMaskPolicy"
If none targets the Contact PII you need, author one with the
two-step recipe (the
Metadata shape is a thin shell; membership is Tooling-inserted):
- Metadata-deploy the thin shell in mdapi format ( + ; a
source-format deploy fails "Could not infer a metadata type"). The shell carries
only , , . This creates the policy with an active
revision, which A2 requires.
- Tooling-insert the (one per object) then its
rows. Each field row's treatment is () + (a snake_case
token like , , ). There is no column.
Insert order matters: a Tooling-created parent (no active revision) makes the child insert fail
INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY
. Metadata-deploy the shell first.
See
references/policy-authoring.md
for the full recipe and the
token table. Choose a
appropriate to each field; do
not blanket-replace.
A3. Start the masking run (REST run API)
bash
printf '{}' > ./empty-body.json
sf api request rest \
"/services/data/v67.0/platform/data-resilience/data-mask/policies/{policyId}/run" \
--method POST --body @./empty-body.json --target-org <alias>
The endpoint needs an
empty JSON body (
) —
requires
on a POST
even when the API takes no payload.
Pass the file with an prefix (
--body @./empty-body.json
);
without it the literal path is sent as the body and the API returns
. A
returns
,
,
(the run-API
status is UPPERCASE, e.g.
) and
message: "Job started successfully"
. A
/
means a run is already in progress for that policy.
Write NOW, before you poll — do not wait until the end. The masking job takes
several minutes (see below), and the single most common way this task scores zero is the turn
ending during the poll with
no output file written at all. The instant you have the
,
write
with everything known so far (policy Id/label, the run command, the
,
status
, and a "polling for completion…" placeholder for the masked count). Then
update
that same file once the job finishes. A report that exists and says "still running" beats no file;
a fabricated count is worse than either — only fill the count from the detail rows (A5).
A4. Poll to a terminal state (standard SOQL)
Poll
DataMaskPolicyJobRun.Status
until it reaches a
terminal value. Do
not report a
mid-run status as final.
- Mid-run (pre-work): , — the job is queued but not yet abortable
- Mid-run (working): — this is the only state in which abort succeeds
- Terminal: , ,
- Abort target: (single "l")
is not . Abort on a
/
job returns
("Job is not in a running state ... status=PENDING"). You must poll until the status is literally
before you can abort — see Workflow B.
Jobs are slow — expect several minutes, and poll with the bundled script. Data Mask runs on a
backend pool/scheduler with a ~5–10 minute floor: even a tiny (20-row) job usually does not
reach a terminal state or emit detail rows for several minutes after the run starts. This is fixed
overhead, not proportional to row count. Plan the run around it — the single biggest failure mode
is treating the job as instant, polling on a tight interval, and either timing out or writing a
"still pending" report.
Run
as a
single command — do
not hand-roll a SOQL poll loop:
bash
bash scripts/poll-job.sh <alias> <jobRunId> # defaults: cap 600s (10 min), 20s interval
It sleeps on a low-frequency interval, short-circuits the instant a ground-truth detail row appears,
prints the terminal signal (
/
/
) on stdout, and exits
(or
on
timeout).
Call it once and read its result — do not wrap it in your own retry loop, and do not
poll on a sub-10s interval (it just burns tool calls against a job that cannot finish sooner).
Ground truth is the detail rows, not the parent status. The parent
DataMaskPolicyJobRun.Status
can
lag — it may read
/
for a while after masking actually finished. Once a
(or
)
row exists, the masking is done.
already encodes all of this — the bounded interval and timeout, the short-circuit on
the ground-truth detail row, and the terminal-signal exit code — so you do
not re-implement any
of it inline. Run the poller once, read its exit signal, then update
(the stub you wrote
before polling) with the terminal status and the masked count from A5.
A5. Report results from the job DETAIL object
The parent job carries an overall status;
per-object masked counts live on the child
(linked by
). Report a concrete count, not a
fabricated one:
bash
sf data query --target-org <alias> \
--query "SELECT Id, DataMaskPolicyJobRunId, Status FROM DataMaskPolicyJobRunDtl WHERE DataMaskPolicyJobRunId = '<jobRunId>'"
Report only what the rows literally show — do not overstate granularity. The detail rows are
object-level status_update entries (
,
,
for the object,
e.g. Contact). They are
not per-field rows. So state per-object success as an observed fact
("Contact: 27/27 records masked, 0 error rows"), but frame field-level success as an
inference,
not a direct observation — say "no field-level error rows were returned, so no field is reported as
failed",
not "all 5 fields succeeded" (the data does not carry a per-field success row to back
that claim). Overstating an inference as an observation is the most common factuality miss here.
Workflow B — Cancel a run
Use this workflow when the request is to abort/cancel a masking run. It targets the run that is
currently in progress — aborting is an on-demand action against a live job; nobody starts a job
just to cancel it. Steps B1–B4 are all required.
B1. Confirm sandbox + identify the run to cancel
Confirm the org is a sandbox (
) and get the
of the run to abort — the one
the user is asking to cancel.
Capture its too — you need it to start a
replacement run if the abort window is missed (B2 exit 3 / exit 1). If they just started it, use that
id; otherwise query for the active run:
bash
sf data query --target-org <alias> \
--query "SELECT Id, Status, DataMaskPolicyId FROM DataMaskPolicyJobRun ORDER BY CreatedDate DESC LIMIT 5"
Note the
(
prefix) of the run you pick — that is the
A3 needs.
B2. Wait for the job to be (the only abortable state)
You can only abort while
DataMaskPolicyJobRun.Status
is
. A
/
job
s; a terminal one is already done. Poll for the
window with the bundled poller in its
mode — it exits the instant the status reads
(unlike the default mode, which
waits for a terminal state), so it will not block past the abortable window:
bash
POLL_MODE=running bash scripts/poll-job.sh <alias> <jobRunId> 900 15
The cap is 900s (15 min), above the ~5–10 min scheduling floor so a slow-to-start job still gets
caught. Handle every exit:
- Exit (prints ) → go straight to B3.
- Exit → the job raced to a terminal state before was caught; the abort window is
gone. Start a fresh run against the policy you captured in B1 (A3 with that ), then
return here and poll the new .
- Exit (timeout — the cap expired) → re-query the job's status:
bash
sf data query --target-org <alias> \
--query "SELECT Id, Status FROM DataMaskPolicyJobRun WHERE Id = '<jobRunId>'"
Because of the ~5–10 min pool floor the
window is usually minutes wide, so there is time to
catch it; do not poll with no delay.
If no run is currently in progress (the job already completed, or you must reproduce a
run→cancel flow end to end), start one first with A3, then return here — poll it to
and
abort
that live job. Never substitute an older, already-terminal job to "show" a cancel; the
abort must target the run that is actually live.
B3. Abort via the run API
Abort via the run API — not by DML/delete on the job record:
bash
sf api request rest \
"/services/data/v67.0/platform/data-resilience/data-mask/jobs/{jobRunId}/abort" \
--method POST --body @./empty-body.json --target-org <alias>
Empty JSON body (
) via the
-prefixed file, as above. A
returns
(uppercase, from the run API) and
message: "Job abort requested"
. A
means the job was not in
a
state (usually still
/
) — return to B2 and resume polling.
B4. Confirm and report the cancellation
Cancellation is asynchronous.
Re-query and confirm
(lowercase, from SOQL) before reporting the abort succeeded. Verify:
High-Signal Rules
| Rule | Rationale |
|---|
| Run each command bare — never add a pipe or redirect of any kind (, , , , , ) | already prints clean JSON on stdout; read it directly. A redirect/pipe trips an unbypassable shell-safety guard that silently stalls the whole run to timeout. Never post-process with //, and never suppress stderr — even if a command prints a warning, the payload on stdout is still valid; just parse it as-is |
| Never use standard SOQL / on config objects | They return / — use Tooling API or MDAPI |
| Read masked counts from , never invent them | The child detail is the source of truth for per-object results |
| Only / / are terminal | Reporting / as final is wrong |
| Abort only via the run-API abort endpoint | DML/delete on the job record is not a real abort and corrupts state |
| Always re-query status after abort and confirm | An abort call returning 200 is not proof the job stopped |
| Data Mask runs on sandboxes only | Run/abort endpoints on production |
| Use API version or later, and no segment | The run/abort endpoints are /services/data/v67.0/platform/data-resilience/data-mask/...
|
| Poll via (one call), never a hand-rolled SOQL loop | The script caps attempts and short-circuits on the ground-truth detail row; a manual loop against the lagging parent status is the #1 cause of a run timing out with no report |
Gotchas
| Issue | Resolution |
|---|
sf sobject describe DataMaskPolicy
| It's a Tooling/MDAPI entity — query with , don't retry standard API |
SELECT ... FROM DataMaskPolicy
| Same cause — use Tooling API for the policy; standard API only for / |
| Run start returns | A run is already in progress for that policy — poll the existing one or wait for it to finish |
| Abort returns "status=PENDING" | The job is still /, not yet — keep polling and abort only once it reads ; don't give up on the abort |
| Small job finishes before you can abort it | The window is seconds on a small sandbox — start a fresh run and poll tightly; never substitute a previously-aborted job to fake the flow |
| Abort returns but SOQL status still | Cancellation is async — keep polling the SOQL status until ; don't report success early |
| Run API says but SOQL says | Case + surface differ: the run API is UPPERCASE, SOQL picklist is lowercase. Trust the SOQL value for terminal state |
| Job "finished" instantly | Re-check: is not terminal. Poll until a terminal value actually appears |
| Run/abort endpoint | The path must be /services/data/v67.0/platform/data-resilience/data-mask/...
references/api-surface.md
|
Output Format
Report the sections for the workflow you ran — do not add sections for the other one. Keep it
tight — show each command once, at the step it belongs to; do not append a second "full command log"
that repeats calls already shown. Prefer a compact table over prose; a reader should reach the key
result in the first screenful.
Workflow A (mask & report):
- Policy used (Id + label, and whether reused or created)
- Run — job Id, final terminal status, masked-record count (from the detail object). Collapse
the poll loop to one line (e.g. "polled 5×, →"); do not print a row per poll.
- Per-object results — from . Report the object-level counts the rows
actually carry; if there are no field-level error rows, say so as an inference ("no field-level
errors reported"), not as a claimed per-field success. See A5 for the exact phrasing.
- Commands run — already shown inline above; here just list any not yet shown. Do not
re-paste the full sequence a second time.
Workflow B (cancel a run):
- Job cancelled — the job Id, that it was when aborted, that the abort was issued via
the run-API abort endpoint, and the re-queried status.
- Commands run — as above, no re-pasting.
Accuracy notes that keep factuality high:
- The run/abort REST response returns a 15-character (e.g. ); SOQL
returns the 18-character form of the same record (e.g. ). They are the
same job — when both appear, note that rather than presenting them as two IDs.
- Do not assert a masked count, a per-field outcome, or a terminal status you did not actually query.
Every number in the report must trace to a query result shown in the command log.
Cross-Skill Integration
| Need | Delegate to | Reason |
|---|
| Seed realistic PII records to mask | platform-data-manage | Test-data creation |
| Author custom anonymization Apex | platform-apex-generate | Apex authoring |
| Deploy the policy metadata to the org | platform-metadata-deploy | Metadata deployment |
Reference File Index
| File | When to read |
|---|
references/api-surface.md
| Exact per-entity API surface, all CLI commands, run/abort REST endpoints, and status picklist values |
references/policy-authoring.md
| Two-step authoring recipe (MDAPI thin shell → Tooling object/field inserts) and the / treatment table |
references/run-and-abort.md
| The run → poll → report → re-run → abort sequence in full, with sample responses |
| Bounded poller: waits for a terminal status (default) or, with , for the abortable window |