Platform Datamask Run

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 403 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 → platform-apex-generate
• seeding or generating test data → platform-data-manage
• deploying unrelated metadata → platform-metadata-deploy

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.

Concretely:

• sf sobject describe --sobject DataMaskPolicy → NOT_FOUND (don't retry it against standard API)
• SELECT ... FROM DataMaskPolicy via sf data query → INVALID_TYPE
• 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:

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:

sf org display --target-org <alias> --json

A2. Identify or create the policy

Prefer reusing an existing policy (fastest, no deploy):

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 DataMaskPolicy Metadata shape is a thin shell; membership is Tooling-inserted):

1. Metadata-deploy the thin shell in mdapi format (--metadata-dir + package.xml; a source-format --source-dir deploy fails "Could not infer a metadata type"). The shell carries only <label>, <description>, <runOnRefresh>. This creates the policy with an active revision, which A2 requires.
2. Tooling-insert the DataMaskPolicyObject (one per object) then its DataMaskPolicyField rows. Each field row's treatment is MaskingCategory (library) + MaskValue (a snake_case token like first_name, email, phone). There is no MaskingRuleType 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 MaskValue token table. Choose a MaskValue appropriate to each field; do not blanket-replace.

A3. Start the masking run (REST run API)

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 ({}) — sf api request rest requires --body 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 JSON_PARSER_ERROR. A 200 returns jobRunId, policyId, status (the run-API status is UPPERCASE, e.g. RUNNING) and message: "Job started successfully". A 409/CONFLICT means a run is already in progress for that policy.

Write report.md 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 jobRunId, write report.md with everything known so far (policy Id/label, the run command, the jobRunId, status RUNNING, 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): pending, scheduled — the job is queued but not yet abortable
• Mid-run (working): running — this is the only state in which abort succeeds
• Terminal: completed, completed_with_errors, failed
• Abort target: canceled (single "l")

pending is not running. Abort on a pending/scheduled job returns 409 CONFLICT ("Job is not in a running state ... status=PENDING"). You must poll until the status is literally running 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 scripts/poll-job.sh as a single command — do not hand-roll a SOQL poll loop:

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 (completed/failed/canceled) on stdout, and exits 0 (or 1 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 pending/running for a while after masking actually finished. Once a total_records_masked (or completed) DataMaskPolicyJobRunDtl row exists, the masking is done. poll-job.sh 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 report.md (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 DataMaskPolicyJobRunDtl (linked by DataMaskPolicyJobRunId). Report a concrete count, not a fabricated one:

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 (loaded, completed, total_records_masked 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 (sf org display) and get the jobRunId of the run to abort — the one the user is asking to cancel. Capture its DataMaskPolicyId 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:

sf data query --target-org <alias> \
  --query "SELECT Id, Status, DataMaskPolicyId FROM DataMaskPolicyJobRun ORDER BY CreatedDate DESC LIMIT 5"

Note the DataMaskPolicyId (8dm prefix) of the run you pick — that is the <policyId> A3 needs.