/platform-sandbox-configure

name: platform-sandbox-configure
description: "MUST USE this skill for ANY sandbox request — including simply getting a sandbox's details, status, license type, or pending-activation state by name or ID. TRIGGER when the user: types \"sandbox -help\"/\"sandbox help\"; mentions a sandbox ID (07E prefix); asks to list or show sandboxes; asks for the details, status, license type, or config of a sandbox by name or ID; activates or discards a completed refresh; deletes a sandbox; verifies activation or deletion; creates or refreshes a sandbox. DO NOT TRIGGER when: the user wants to clone a sandbox."
metadata:
  version: "1.1"
  domains: ["Platform"]
  minApiVersion: "66.0"
  relatedSkills:
    - "automation-sandbox-post-copy-config-generate"
    - "automation-sandbox-post-copy-configure"
  accessCheck:
    - type: "userPerm"
      value: "ManageSandboxes"
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"

Sandbox Lifecycle Management

Manage Salesforce sandbox environments through Connect REST API — list inventory, activate or discard completed refreshes, create and refresh sandboxes, and permanently delete sandboxes.

When This Skill Owns the Task

Use `platform-sandbox-configure` when the work involves:

• Listing or retrieving all sandboxes (GET /sandbox/reports)
• Getting details or status of a specific sandbox by name or by ID (07E prefix)
• Checking license usage and remaining capacity by license type (GET /sandbox/licenses)
• Activating a sandbox after a refresh completes (applying the refresh)
• Discarding a completed refresh (keeping existing sandbox data unchanged)
• Permanently deleting a sandbox to free up licenses
• Verifying activation or deletion completed
• Creating a new sandbox (Developer, Developer Pro, Partial Copy, or Full)
• Refreshing an existing sandbox with latest production data

Delegate elsewhere when the user is:

• Cloning a sandbox → Tooling API (`SandboxInfo` sObject)
• Generating a post-copy automation JSON config from an SOP → `automation-sandbox-post-copy-config-generate`
• Applying/running a post-copy automation JSON config against a sandbox → `automation-sandbox-post-copy-configure`

---

Help (Interactive Menu)

When the user types `sandbox -help` or `sandbox help`, respond with ONLY a text message showing the numbered operation list below. **Do NOT call any API or tool — just display this menu and wait for the user to reply with a number.**

The agent MUST respond with this exact markdown (not in a code block — render it directly as a bullet list):

**Sandbox Lifecycle Management**

**1. Inventory & Details**

• a. List all sandboxes — Names, types, statuses, IDs
• b. Get details (by name) — Status, license, config
• c. Get details (by ID) — Provide a 07E ID directly
• d. Check license usage — Available vs. used counts by license type

**2. Create & Refresh**

• a. Create a new sandbox — Dev, Dev Pro, Partial, Full
• b. Refresh a sandbox — Latest production data

**3. Activate, Discard & Delete**

• a. Activate a sandbox — Apply a completed refresh
• b. Discard a refresh — Reject, keep existing data
• c. Delete a sandbox — Permanent removal

**4. Verify & Monitor**

• a. Verify activation status — Check if activate completed
• b. Verify deletion status — Check if delete completed

**5. Post-Copy Automation**

• a. Create Post Copy Automation JSON Configs — Generate a config from an SOP
• b. Run Post Copy Automation — Apply a config JSON to a sandbox

Reply with a code (e.g. "3a") or describe what you need.

**After the user replies, ask for the required input:**

| Selection | Follow-up question | |---|---| | 1a | No input needed — proceed immediately | | 1b | "What's the sandbox name?" | | 1c | "What's the sandbox ID? (starts with 07E)" | | 1d | No input needed — proceed immediately | | 2a | First call `GET /sandbox/licenses` (Section 9) and show available/used counts; then ask for name + license type (Developer, Developer_Pro, Partial_Copy, Full) | | 2b | First call `GET /sandbox/reports` (Section 1) and list refresh-eligible sandboxes (`isPendingActivation: false`); then ask which to refresh | | 3a | "Which sandbox? Provide a name or 07E ID." | | 3b | "Which sandbox? Provide a name or 07E ID." | | 3c | "Which sandbox? Provide a name or 07E ID." | | 4a | "Which sandbox did you activate? Provide a name or 07E ID." | | 4b | "Which sandbox did you delete? Provide a name or 07E ID." | | 5a | "Delegating to the post-copy config generator — please share the SOP (file, text, or screenshot)." | | 5b | "Delegating to the post-copy config runner — please share the config JSON file and the target sandbox." |

Execute the corresponding operation below. **Exception:** 5a/5b delegate — 5a → `automation-sandbox-post-copy-config-generate`; 5b → `automation-sandbox-post-copy-configure`. This skill does not implement post-copy automation; do not generate or apply a config directly.

---

API Base

**CRITICAL:** For sandbox operations in this skill, use the Connect REST API. Two discovery paths exist:

• **By name:** Call `GET /sandbox/reports` to list all sandboxes and find the matching one by `sandboxName`.
• **By ID (07E prefix):** Call `GET /sandbox/sandboxes/{sandboxId}` directly — do NOT call `/sandbox/reports`.

Both paths return sandbox records with `sandboxId` (prefix `07E`) which is required for all lifecycle mutation operations.

sf api request rest "/services/data/v66.0/sandbox/reports" --method GET

See `references/api-response-shapes.md` for the full response shape.

**IMPORTANT:** Do NOT use Tooling API (`SandboxInfo`/`SandboxProcess`) for discovery — mutation endpoints require the Connect REST API's `sandboxId` (07E), NOT `SandboxInfo.Id` (0GQ) or `SandboxProcess.Id` (0GR).

**NEVER use SOQL / `run_soql_query` / `sf data query` for lifecycle reads (status, inventory, details, license, pending-activation).** This data lives ONLY in the Connect REST API — no SObject returns it. (`sf data query --use-tooling-api` on `SandboxInfo`