/platform-datamask-run

name: platform-datamask-run
description: "Data Mask end-to-end operation on a sandbox: configure a masking policy over PII, run the masking job, poll it to completion, report masked-record results, and abort an in-progress run. Use when the user needs to run, monitor, or cancel a Salesforce Data Mask job, mask PII/sandbox data, or work with DataMaskPolicy / DataMaskPolicyJobRun. TRIGGER when: user runs a data mask job, masks sandbox PII, polls masking status, reports masked records, or aborts a running mask. DO NOT TRIGGER when: writing anonymization Apex by hand (use platform-apex-generate), generating test data (use platform-data-manage), or deploying unrelated metadata (use platform-metadata-deploy)."
metadata:
  version: "1.0"
  domains: ["Platform"]
  minApiVersion: "67.0"
  relatedSkills:
    - "platform-apex-generate"
    - "platform-data-manage"
    - "platform-metadata-deploy"
  cliTools:
    - tool: ["python3"]
      semver: ">=3.10.0"
    - tool: ["sf"]
      semver: ">=2.0.0"
  accessCheck:
    - type: userPerm
      value: PermissionsManageDataMaskPolicies
    - type: userPerm
      value: PermissionsAccessDataMaskAndSeed

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.

| Entity | What it is | How you reach it | |--------|-----------|------------------| | `DataMaskPolicy` | The masking policy shell (config) | **Tooling API** or **Metadata API** (thin shell: `<label>`/`<description>`/`<runOnRefresh>` only) — NOT standard SOQL/`sobject describe` | | `DataMaskPolicyObject` | An object targeted by a policy (holds the optional row filter) | **Tooling API only** — query AND insert; row-subset "sample" runs set `FilterEnabled`+`WhereCriteria` here (no `sampleSize` on the policy) | | `DataMaskPolicyField` | A field + its masking treatment | **Tooling API only** — query AND insert; treatment cols are `MaskingCategory` + `MaskValue` | | `DataMaskPolicyJobRun` | The **job** (one masking run) | **Standard SOQL** — `sf data query` works | | `DataMaskPolicyJobRunDtl` | Per-object **job detail** (child, FK `DataMaskPolicyJobRunId`) | **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` → **`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:

| 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 `canceled` |

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