forcedotcom/sf-skills / plugins/builder/dx-org-lifecycle/skills/automation-sandbox-post-copy-configure
automation-sandbox-post-copy-configure
VerifiedApply a Salesforce sandbox post-copy automation JSON config against a target org. Use when the user asks to apply, run, execute, dry-run, or preview a post-copy or post-refresh config file (e.g. `post-copy-config.json`) against a sandbox — including activating/deactivating a Flow (PATCH `FlowDefinition.Metadata.activeVersionNumber` to the version, or `null`), re-pointing an OBM endpoint, updating a RemoteSiteSetting URL, or re-scheduling a ScheduledApex job after refresh. Also trigger for phrasings like "apply post-copy config", "run post-copy automation", "activate Flow <name> post-refresh", "deactivate Flow <name>", "re-point outbound messages after refresh", or "configure sandbox after refresh". Per entry, derive the Tooling API sobject, verify via describe, resolve the Id via SOQL, then PATCH the compound `Metadata` field (`ScheduledApex` uses anonymous Apex). DO NOT TRIGGER for generating config JSON from an SOP (use `automation-sandbox-post-copy-config-generate`) or for deploying metadata XML.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 21.3 KB |
| assets/api_request_templates.json | config | 4.2 KB |
| examples/sample_config_input.json | config | 1.1 KB |
| examples/sample_execution_summary.md | markdown | 4.0 KB |
| references/api_endpoints.md | markdown | 10.7 KB |
| references/authentication.md | markdown | 2.9 KB |
| references/execution_phasing.md | markdown | 3.6 KB |
| references/flow_activation_path.md | markdown | 7.1 KB |
| references/rules_gotchas.md | markdown | 3.5 KB |
| references/scheduled_apex_path.md | markdown | 8.1 KB |
| scripts/build-scheduled-apex.mjsexecutable | script | 2.2 KB |
| scripts/classify-patch-result.mjsexecutable | script | 3.1 KB |
| scripts/map-metadata-key.mjsexecutable | script | 3.4 KB |
| scripts/plan-phases.mjsexecutable | script | 2.8 KB |
| scripts/resolve-target-org.mjsexecutable | script | 1.9 KB |
| scripts/soql-escape-job-name.mjsexecutable | script | 1.0 KB |
references/scheduled_apex_path.md
View on GitHub# Step F — Scheduled Apex (anonymous Apex route)
`ScheduledApex` entries in the post-copy config target the `CronTrigger`
sobject, which is **read-only** in the Tooling API — there is no
compound `Metadata` field, so Steps A–E (describe → SOQL → GET+PATCH)
cannot apply. Instead this route runs anonymous Apex
`System.schedule(...)` via `sf apex run` and verifies via a
`CronTrigger` SOQL read-back.
## Fields shape
Every `ScheduledApex` entry must carry these three keys under `Fields`:
| Key | Meaning |
|-----|---------|
| `ApexClassName` | Bare Apex identifier of the class that implements `Schedulable`. |
| `CronExpression` | Salesforce cron expression (6- or 7-field). |
| `JobName` | Human-readable job name. Appears in Setup > Scheduled Jobs; equals `CronTrigger.CronJobDetail.Name` post-schedule. |
If any of the three is missing, mark the entry `API_NOT_IDENTIFIED` and
skip. Never fabricate one from the others.
## Prerequisites
The Apex `Schedulable` class named by `ApexClassName` must already exist
on the target sandbox. Sandbox refresh copies class metadata from source
to target, so this is normally satisfied on a fresh refresh — the reason
scheduled *jobs* need re-creation is that `CronTrigger` records (runtime
state) don't copy, not that the classes don't.
If the class is genuinely missing, F-3 (`sf apex run`) fails at compile
with `Variable does not exist: <ApexClassName>` — the outcome becomes
`FAILED` and the customer follows the Cross-Skill Integration row on
`platform-metadata-deploy` to deploy the class before re-running this
skill.
## F-1 — Pre-flight AMBIGUOUS check
`System.schedule` throws `AlreadyScheduledException` if a job with the
same name already exists. Query first to avoid that path — and per skill
policy, do NOT auto-abort an existing job; surface it as `AMBIGUOUS` so
the customer decides.
`JobName` is human-readable and may legitimately contain an apostrophe
(e.g. `Owner's nightly job`). Never inline it into the SOQL literal
directly — escape it via the deterministic helper first, which also
rejects the same characters `scripts/build-scheduled-apex.mjs` rejects
(newlines/backslashes), so an input that passes F-1 will also pass F-2:
```bash
JOB_NAME_LITERAL=$(node scripts/soql-escape-job-name.mjs "<Fields.JobName>") || {
# Non-zero exit → outcome FAILED with stderr in Follow-ups; skip F-2/F-3/F-4.
exit 1
}
SOQL="SELECT Id FROM CronTrigger WHERE CronJobDetail.Name = '$JOB_NAME_LITERAL'"
sf data query --json --query "$SOQL" > /tmp/entry-<Slug>-cron.json
COUNT=$(jq -r '.result.totalSize' /tmp/entry-<Slug>-cron.json)
```
Outcomes:
- `COUNT == 0` → proceed to F-2.
- `COUNT >= 1` → outcome `AMBIGUOUS`. Add a Follow-ups bullet listing
the entry's `Fields.JobName` and every returned `CronTrigger.Id`.
Do not attempt to schedule.
In dry-run, still run F-1 — it is a read.
## F-2 — Build the anonymous Apex snippet
Never author the snippet from memory — Apex string escaping is a common
foot-gun. Use the deterministic builder:
```bash
node scripts/build-scheduled-apex.mjs \
"<Fields.JobName>" \
"<Fields.CronExpression>" \
"<Fields.ApexClassName>" \
assets/scheduled_apex_template.apex \
> /tmp/entry-<Slug>.apex
```
The script:
- Verifies `CronExpression` is 6- or 7-field whitespace-separated.
- Verifies `ApexClassName` matches `^[A-Za-z_][A-Za-z0-9_]*$`.
- Rejects newlines and backslashes in any input (would either break the
string literal or enable Apex injection).
- Single-quote-escapes `JobName` and `CronExpression` for embedding in
the Apex single-quoted string.
- Writes the substituted `.apex` snippet to stdout.
Non-zero exit → outcome `FAILED` with stderr in Follow-ups.
## F-3 — Execute the snippet
```bash
sf apex run --file /tmp/entry-<Slug>.apex --json \
> /tmp/entry-<Slug>-apex.json
```
Classify from the JSON response:
| `.result.compiled` | `.result.success` | Outcome | Follow-ups body |
|--------------------|-------------------|---------|-----------------|
| `false` | (any) | `FAILED` | `.result.compileProblem`, `.result.line`, `.result.column` |
| `true` | `false` | `FAILED` | `.result.exceptionMessage`, `.result.exceptionStackTrace` |
| `true` | `true` | proceed to F-4 | — |
Skip F-3 entirely in dry-run and record `DRY_RUN`.
## F-4 — Verify the job scheduled
Reuse `$JOB_NAME_LITERAL` from F-1 — it is the same JobName, already
SOQL-escaped and validated:
```bash
SOQL="SELECT Id, State, NextFireTime, CronExpression FROM CronTrigger WHERE CronJobDetail.Name = '$JOB_NAME_LITERAL'"
sf data query --json --query "$SOQL" > /tmp/entry-<Slug>-verify.json
```
Outcomes:
- 0 rows → `FAILED_VERIFY` (apex reported success but no CronTrigger
materialized — usually a permission or platform limits issue).
- ≥1 row where `.CronExpression == '<Fields.CronExpression>'` → `SUCCESS`.
- ≥1 row with a different `CronExpression` → `FAILED_VERIFY` (something
else claimed the name after F-1 saw it clear).
Skip F-4 entirely in dry-run (nothing to verify).
## Summary shape for a Step F entry
The generic `Planned request:` block from SKILL.md's canonical output
shape does **not** apply to a ScheduledApex entry — the Step F path
dispatches across four distinct sub-steps (pre-flight SOQL, snippet
build, `sf apex run`, verify SOQL), so the summary must record
evidence that each sub-step ran, not just the final `sf apex run`.
Replace the `Planned request:` block with the labeled narrative
below, keeping the single-row phase table and the Totals /
Follow-ups sections unchanged.
For each ScheduledApex entry's phase block, emit (in this order):
1. A one-line route header:
```text
Route: **Step F — Scheduled Apex (anonymous Apex)**. No describe probe on this route; `CronTrigger` is read-only.
```
2. `Pre-flight AMBIGUOUS check:` — the F-1 SOQL and the single-row
`totalSize` result (never a bulk count claim), ending with the
decision (`totalSize = 0 → proceed to F-2` /
`AMBIGUOUS short-circuit — N existing CronTrigger rows`). Emit the
SOQL verbatim, with `JobName` single-quoted as it appeared on the
wire (post-SOQL-escape); do not paraphrase.
3. `Request executed:` — the F-2/F-3 artifacts as **three separate
bullets** (not Method/Path/Body sub-structure):
- `Snippet path:` — the `/tmp/entry-<Slug>.apex` path F-2 wrote.
- `Snippet body:` — the exact one-line
`System.schedule('<JobName>', '<CronExpression>', new <ApexClassName>());`
string F-2 produced, with the same single-quote-escaping F-2
applied (not the pre-escape input).
- `Command:` — the exact
`sf apex run --file /tmp/entry-<Slug>.apex --json` invocation
F-3 ran.
On dry-run, rename this section to `Planned request (F-2, dry-run):`,
keep only the `Snippet path:` and `Snippet body:` bullets (omit
`Command:` — F-3 is skipped), row Outcome is `DRY_RUN`, and skip
section 5 below.
4. The single-row phase table (unchanged from SKILL.md's canonical
shape):
- `Sobject` column reads `CronTrigger`.
- `Describe` column reads `—` (no describe probe on this route).
- `HTTP` column reads `—` (no direct HTTP status; `sf apex run`
bundles compile + execute into one response).
5. `Read-back verification:` — the F-4 SOQL verbatim and the
observed row (`N row(s) with CronExpression = "<value>"`),
confirming the schedule landed. On `0 rows → FAILED_VERIFY`
emit the zero-row result; on `CronExpression mismatch →
FAILED_VERIFY` emit both the expected and observed values.
Short-circuit cases (`AMBIGUOUS` / `API_NOT_IDENTIFIED` /
`FAILED` at F-2 or F-3 / `FAILED_VERIFY`) emit F-1 (and F-2/F-3 if
the failure is visible later) and stop — skip F-4 and the row's
`HTTP` column renders `—`.
## Dry-run recap
| Sub-step | Dry-run behavior |
|----------|------------------|
| F-1 SOQL pre-flight | run (read) |
| F-2 snippet build (writes to `/tmp` only) | run |
| F-3 `sf apex run` | SKIP → record `DRY_RUN` |
| F-4 verify SOQL | SKIP (nothing to verify) |
The "Planned request" printed in the dry-run summary for a Step F entry
is the full contents of the built `.apex` snippet, so the customer can
audit exactly what would have executed.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |