automation-sandbox-post-copy-configure

Automation: Sandbox Post-Copy Configure

Apply a Salesforce sandbox post-copy automation JSON config to a target

org. The skill pins the Tooling API sobject and the record-lookup

SOQL filter for the two canonical ConfigurationName values it has

been calibrated against (OutboundMessages, RemoteSiteSettings); for

any other ConfigurationName it derives a candidate from the entry

value and verifies it against the live org's describe endpoint. Every

entry — pinned or derived — must still pass Step B (describe returns

200 with a Metadata compound field) before any PATCH is planned.

Entries whose API cannot be identified or verified are surfaced in the

summary and skipped — they are never guessed at.

Tool Restrictions

Use ONLY the Bash tool to execute sf CLI commands (`sf data query

--use-tooling-api, sf api request rest, sf org display`). Do NOT

use MCP tools like execute_soql — ignore them completely; the

compound Metadata PATCH pattern this skill requires is not available

through MCP tool wrappers. If the target org alias is not explicitly

named by the user, invoke sf commands without --target-org —

the harness has already set the CLI's default target-org. Never pass

--target-org default — default is not an alias and will fail with

NamedOrgNotFoundError.

SOQL-over-REST (sf data query --use-tooling-api ...) is treated as

an API call — same OAuth session, same authorization boundary as the

subsequent PATCH. No direct database / non-Salesforce SQL access.

STOP — do this before making any API call

Never call the org from memory. Before the first request:

1. Read the config JSON end-to-end from the exact path the user gave

(default ./post-copy-config.json). Every entry must have all five

keys (ConfigurationName, Label, Fields, IsActive,

ExecutionOrder). If any entry is malformed, abort and surface the

file path + entry index — do not partially apply. **Do not

invent entries.** If the file is missing, stop and ask; never

fabricate a plan against synthetic labels.

1. For each distinct ConfigurationName in the config, run the

derivation + describe-verify step (below) before planning any

PATCH. An entry whose API cannot be verified must never appear as

a planned PATCH — it is rejected up front.

1. Confirm the target org alias with the user unless they supplied one

explicitly. This skill mutates a live org — writing to the wrong

org (e.g., a production alias set as default) is the most expensive

failure mode.

If you announce "I will apply … now" without having read the config

file and run the describe-verify for every distinct

ConfigurationName, stop and do those first.

---

Per-entry procedure (the core of this skill)

The skill carries a pinned mapping for the canonical types below, and

a derive-then-verify path for anything else. Follow these steps **for

every entry**, in order. Step B (describe-verify) is mandatory

regardless of whether the mapping came from the pinned table or the

derive path — its HTTP status must appear in the summary.

Step A — Resolve the Tooling API sobject and lookup filter

**Pinned canonicals (authoritative — use these exactly, do NOT

substitute a different sobject name):**

| ConfigurationName | Tooling API sobject | Record-lookup SOQL |

|-------------------|---------------------|--------------------|

| OutboundMessages | WorkflowOutboundMessage | SELECT Id, FullName FROM WorkflowOutboundMessage WHERE EntityDefinition.QualifiedApiName = '<Fields.Object>' — then client-side pick the row whose FullName == '<Fields.Object>.<Label>'. SOQL cannot filter on FullName directly for this sobject. |

| RemoteSiteSettings | RemoteProxy | SELECT Id, SiteName FROM RemoteProxy WHERE SiteName = '<Label>'. |

For canonical entries use the pinned sobject and SOQL as-is; skip

"derive". Do not invent OutboundMessage, RemoteSiteSetting, or

MasterLabel variants — plausible-looking but wrong.

Field-name resolution (overrides + case rule + existence check) is

owned by scripts/map-metadata-key.mjs.

Non-canonical: derive a candidate (usually singular of the

Metadata API type name, sometimes prefixed); Step B rules out wrong

guesses. Use the generic SOQL patterns in Step C.

Step B — Verify the candidate exists and supports Metadata writes

For each candidate, GET the describe:

sf api request rest \
  "/services/data/v<apiVersion>/tooling/sobjects/<Candidate>/describe/"

Accept the candidate only if both are true:

• HTTP 200 (the sobject exists on this org's Tooling API), AND
• The describe response's fields array contains a field named

Metadata (compound field — this is what PATCH writes through).

If no candidate passes both gates, mark the entry

API_NOT_IDENTIFIED and skip. Do not guess a REST path — the

wrong path 404s in the best case and updates the wrong record in the

worst case.

Step C — Resolve the record Id (SOQL-over-REST)

For pinned canonicals: run the SOQL from the Step A table

verbatim (substituting <Label> / <Fields.Object>). Do not

substitute a different filter column such as MasterLabel — the

pinned SOQL is the tested-and-correct filter for that sobject.

For non-canonical (derived) sobjects: query the verified sobject

for the record identified by the entry's Label (and Fields.Object

when present):

# SOQL to a variable + separate jq call — avoids the most common
# shell-quoting failure in this skill.
SOQL='SELECT Id, FullName FROM <VerifiedSobject> WHERE <UniqueFilter>'
sf data query --use-tooling-api --json --query "$SOQL" \
  > /tmp/entry-<Slug>-lookup.json
ID=$(jq -r '.result.records[0].Id // empty' /tmp/entry-<Slug>-lookup.json)

Pick <UniqueFilter> based on the queryable fields shown in the

describe response from Step B. If the row contains a FullName field,

SOQL usually rejects a direct FullName = ... filter — filter by

whichever direct column the describe surfaces (e.g.

EntityDefinition.QualifiedApiName, DeveloperName, SiteName) and

apply the FullName match client-side (`jq -r

'.result.records[] | select(.FullName == "<Object>.<Label>") | .Id'`).

Outcomes:

• Zero rows → NOT_FOUND (never fall back to insert).
• Multiple rows after client-side filtering → AMBIGUOUS (surface

all Ids in the summary and skip; a wrong Id is worse than no Id).

• Exactly one row → proceed to Step D.

Step D — GET current Metadata, mutate, PATCH back

Metadata is replace-in-full — omitted keys are blanked on

PATCH. Preserve every existing key from the Step D-1 GET; overlay

only the mutated keys. The summary's "planned PATCH body" (apply

and dry-run) is this full merged object — verbose or org-specific

values may render as "<preserved-from-GET>" in dry-run, but

every key must be present.

Every Step D filename must include the record <Id> from Step C

(e.g. /tmp/entry-<Id>-meta.json) — phase-parallel entries share

the working directory and would clobber a shared name.

1. GET current Metadata → /tmp/entry-<Id>-meta.json.
2. Resolve the mutation key — for each Fields.<Xxx>, run

`node scripts/map-metadata-key.mjs "<ConfigurationName>"

"<ConfigFieldName>" /tmp/entry-<Id>-meta.json`. On

{"status":"OK","key":...} use the returned key. On

{"status":"FIELD_MAP_UNKNOWN",...} mark the entry and skip.

1. PATCH — heredoc-build /tmp/entry-<Id>-mutation.json, merge

with `jq --slurpfile m /tmp/entry-<Id>-mutation.json

'. + $m[0] | {Metadata: .}' /tmp/entry-<Id>-meta.json >

/tmp/entry-<Id>-patch.json` (preserves JSON types), PATCH with

-b @/tmp/entry-<Id>-patch.json, capture the response body to

/tmp/entry-<Id>-response.json. Full bash in

references/api_endpoints.md §Step D. Never use --arg

(stringifies booleans/numbers, breaks on special chars). Wrap

the PATCH in for attempt in 1 2; do <cmd> && break; done —

retry once on shell/jq quoting failure (non-zero exit before

the HTTP call goes out).

1. Classify — `node scripts/classify-patch-result.mjs

"<httpCode>" /tmp/entry-<Id>-response.json. Exit 0 → SUCCESS`;

exit 2 → FAILED (parsed error on stdout). 204 with a non-empty

body is FAILED.

Step E — Verify the change landed

Re-read the record to confirm the PATCH stuck:

• If the mutated field is a direct-queryable SOQL column on the

sobject (rare — most Metadata-writable fields are not), a SELECT

by Id is enough.

• Otherwise GET the record and inspect the corresponding key inside

.Metadata.

If the read-back value doesn't match the requested value, record

FAILED_VERIFY — the PATCH returned 204 but the effect is not

visible (usually a naming or permission issue).

---

IsActive semantics

• IsActive: true → apply the PATCH as described in Steps A–E.
• IsActive: false → do not PATCH. Record SKIPPED_INACTIVE

for the entry and add a bullet under Follow-ups in the summary

file listing the entry's ConfigurationName + Label so the

customer notices that a config-declared inactive record was left

untouched on the target org.

Rationale: IsActive: false means "not active in this sandbox",

not "deactivate the existing record". Silently deactivating a live

integration is a much bigger blast radius than leaving it alone.

---

Canonical output shape (always emit this)

Single Markdown summary written to ./post-copy-<mode>-summary.md

(mode is dry-run or apply) AND printed to the user. No JSON

side-files (plan/phases.json, requests/*.request.json, etc.) —

inline every planned/actual request in the Markdown.

Phase enumeration is script-owned. Run `node scripts/plan-phases.mjs

<config.json> and consume its phases[]` output verbatim. Each entry

carries ordinal (1-indexed phase number) and executionOrder (raw

value, for the (ExecutionOrder = <raw>) heading annotation). Sparse

values collapse (1, 2, 5 → ordinals 1, 2, 3). IsActive:false

entries are pre-marked SKIP_INACTIVE. See

references/execution_phasing.md for the worked example.

For dry-run entries the HTTP column is — (em-dash). End the

summary with: `No PATCH requests were issued. To apply, re-run

without the dry-run flag.`

Target-org resolution is script-owned. Run `node

scripts/resolve-target-org.mjs; substitute the returned .alias`

into the header. Never emit <env:SF_TARGET_ORG> or $SF_TARGET_ORG

verbatim.

# Post-Copy Configure Run — <N> entries <planned|applied> against `<alias>`

Config file: `<path>`
Target org: `<alias>`
Mode: <dry-run|apply>

## Phase <ExecutionOrder> — <count> entr(y|ies)

Planned request:
- Method: `PATCH`
- Path: `/services/data/v<apiVersion>/tooling/sobjects/<VerifiedSobject>/<Id>`
- Body: `<JSON — the FULL merged Metadata object: every existing key from the Step D-1 GET, overlaid with the mutated keys from the config. Preserved keys with verbose or org-specific values may appear as "<preserved-from-GET>" placeholder strings, but every key must be present. NEVER emit a minimal body containing only the mutated keys.>`

| ConfigurationName | Label | Object | Sobject | Describe | Outcome | HTTP |
|-------------------|-------|--------|---------|----------|---------|------|
| <name>            | <lbl> | <obj>  | <VerifiedSobject> | <200 or 404> | <outcome> | <code> |

## Totals

| Outcome | Count |
|---------|-------|
| <state> | <n>   |

## Follow-ups

- <bullet per SKIPPED_INACTIVE / API_NOT_IDENTIFIED / AMBIGUOUS / FIELD_MAP_UNKNOWN / NOT_FOUND entry>

Column semantics: Object = the entry's Fields.Object if present,

— otherwise. Sobject = the Step A resolved sobject. Describe =

the Step B describe HTTP status (200 for verified, 404 for

API_NOT_IDENTIFIED) — mandatory so skipped Step Bs are visible at a

glance. Outcome vocabulary: SUCCESS, NOT_FOUND, AMBIGUOUS,

API_NOT_IDENTIFIED, FIELD_MAP_UNKNOWN, FAILED, FAILED_VERIFY,

SKIPPED_INACTIVE, SKIPPED, DRY_RUN, DELETE_NOT_SUPPORTED,

NOT_ATTEMPTED.

Scripts are internal. The plan-phases.mjs, map-metadata-key.mjs,

classify-patch-result.mjs, resolve-target-org.mjs invocations are

implementation detail — do not inline their raw stdout, JSON

output, or "I ran node …" narration into the summary Markdown or

the printed response. Consume the JSON, use the returned values, and

render the summary in the exact shape above.

Scope

• In scope: Reading a post-copy config JSON (the shape produced

by automation-sandbox-post-copy-config-generate), grouping entries

into ExecutionOrder phases, deriving+verifying the Tooling API

sobject for each entry, resolving Ids via SOQL-over-REST, PATCHing

via compound Metadata, and reporting per-entry outcomes.

• Out of scope: Generating the config JSON from an SOP (delegate

to automation-sandbox-post-copy-config-generate); deploying

metadata XML; running the Async Task Framework (ATF) orchestrator

itself (that is the platform-side Java implementation); inventing

API paths for ConfigurationName values whose describe probe

fails (surface as API_NOT_IDENTIFIED and stop).

Every API call is against a live org. Treat this skill as a mutation

tool: prefer --dry-run first, confirm the target org alias, and

never silently retry a failed entry against a different endpoint.

---

Required Inputs

Gather or infer before applying:

• Config file path: Path to the JSON produced by

automation-sandbox-post-copy-config-generate (default:

./post-copy-config.json in the current directory). If the file

does not exist, stop and ask.

• Target org alias / username: The sf CLI alias or username of

the target sandbox. Never assume the default org — always confirm.

If the user has not supplied one, list available orgs with `sf org

list --json` and ask which to use.

• Dry-run flag (optional, default false): Semantics —

reads are ALLOWED, writes are FORBIDDEN. Dry-run means the run

produces no mutation on the target org; it does NOT mean "no

network calls". You MUST still execute every read against the org:

the describe probe (Step B, GET), the SOQL Id lookup (Step C,

sf data query), and the record fetch (Step D-1, GET) — because

the plan's "would-be PATCH body" can only be accurate if the

agent has read the current Metadata block from the live record.

The ONLY skipped calls are the writes: Step D-3 (PATCH) and

Step E (post-PATCH verification). Never fabricate the current

Metadata; never emit a body containing invented keys. If a read

fails (401, 404, NamedOrgNotFoundError), surface the error and

stop — do not fall back to a from-memory plan. Use dry-run on the

first pass unless the user has explicitly asked to apply.

• Continue-on-error (optional, default true): When true, a

failing entry does not abort the phase — the remaining entries in

the phase still execute, and the failure is reported in the

summary. When false, a failure aborts execution mid-phase.

If the user supplies a clear config path and target alias, proceed

without further questions.

---

Workflow

Every step executes real sf CLI commands via the Bash tool. Do NOT

narrate the plan without actually running the commands — the point of

this skill is to mutate the target org, not to describe how.

1. Read and validate the config JSON — load the file with the

Read tool. Every entry must be a JSON object with the five

top-level keys (ConfigurationName, Label, Fields,

IsActive, ExecutionOrder). Malformed entries are a hard stop.

1. Resolve the target org and API version — run

sf org display --json. Parse the JSON to confirm the alias

resolves and to capture result.apiVersion (e.g. 62.0). Do not

print the raw JSON — it contains the access token.

1. Plan phases — run node scripts/plan-phases.mjs <config.json>

and iterate its phases[] output. See

references/execution_phasing.md for the concurrency cap.

1. Per-entry describe-verify pass — for each distinct

ConfigurationName, run Step A + Step B once and cache the

verified sobject. Any ConfigurationName failing Step B marks

every entry with that name as API_NOT_IDENTIFIED.

1. Per-entry apply pass — for each entry inside each phase:

• Entries pre-marked SKIP_INACTIVE by plan-phases → record

SKIPPED_INACTIVE, add a Follow-ups bullet, continue.

• Else run Step C (resolve Id), then Step D (GET+mutate+PATCH),

then Step E (verify). If --dry-run is true, still run Step C

and D-1/D-2 so the printed plan reflects the real merged

payload — skip only D-3 (the PATCH) and Step E, then record

DRY_RUN.

1. Between phases — wait for every entry in the current phase to

complete before starting the next.

1. Write the summary file to disk — the final deliverable is a

Markdown file at ./post-copy-<mode>-summary.md, following the

shape in the "Canonical output shape" section. Also print it to

the user. Never write access tokens or full sf org display

output. If a URL contains embedded credentials, mask them in the

summary (https://user:***@host/...); the actual PATCH body

carries the verbatim URL.

---

Rules and Gotchas

Load-bearing invariants (never insert; describe-gate every

ConfigurationName; compound Metadata PATCH preserves the full

existing block; IsActive: false → SKIPPED_INACTIVE; never print

raw access tokens; cap intra-phase concurrency at 5) and the

canonical response for each runtime failure (401 mid-run, 429,

credential-bearing URLs, Fields.Action = "Delete", describe 404,

zero/many SOQL rows) live in references/rules_gotchas.md. Read

that file before deviating from the Step A–E procedure.

---

Cross-Skill Integration

| Need | Delegate to |

|------|-------------|

| Turn a customer SOP into the JSON config this skill consumes | automation-sandbox-post-copy-config-generate |

| Deploy Salesforce metadata XML (Custom Labels, Named Credentials, etc.) that lives outside the compound-Metadata Tooling API pattern | The matching generating-* skill + a metadata deploy flow |

| Create new records that do not yet exist on the target org | platform-metadata-deploy after generating the metadata XML |

| Assign permission sets required to run the API calls | dx-org-permission-set-assign |

---

Reference File Index

| File | When to read |

|------|-------------|

| references/api_endpoints.md | Steps A–E — the full generic recipe with worked examples (OBM, RSS) and the camelCase-field convention |

| references/execution_phasing.md | Step 3 (workflow) — the grouping rules and the intra-phase concurrency cap. scripts/plan-phases.mjs is the executable source-of-truth for phase enumeration; this file explains the model behind it |

| scripts/plan-phases.mjs | Step 3 (workflow) — deterministic phase planner (invoke, then read its output) |

| scripts/map-metadata-key.mjs | Step D-2 — deterministic Metadata-key resolver (override table + case rule + existence check) |

| scripts/classify-patch-result.mjs | Step D-4 — deterministic HTTP-outcome classifier (SUCCESS vs FAILED) |

| scripts/resolve-target-org.mjs | Canonical output shape — deterministic target-org alias resolver |

| references/authentication.md | Step 2 (workflow) — for the session-check recipe and how to handle 401 mid-run |

| references/rules_gotchas.md | Before deviating from Step A–E — load-bearing invariants and canonical runtime-failure responses |

| assets/api_request_templates.json | Steps A–E — the generic template for describe / lookup / GET+PATCH with placeholder keys |

| examples/sample_config_input.json | Step 1 (workflow) — shape of the config JSON this skill consumes |

| examples/sample_execution_summary.md | Step 7 (workflow) — the shape of the summary report shown to the user |