Platform Sandbox Configure

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)
• 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

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:

Execute the corresponding operation from the Operations section below. Exception: 5a and 5b delegate to a different skill instead of an in-skill operation:

• 5a → Invoke the automation-sandbox-post-copy-config-generate skill.
• 5b → Invoke the automation-sandbox-post-copy-configure skill.

This skill does not implement post-copy automation itself — it only routes to the two skills above. Do not attempt to generate or apply a post-copy config directly from this skill.

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.

# List all sandboxes (Connect REST API)
sf api request rest "/services/data/v66.0/sandbox/reports" --method GET

# Response format:
# {
#   "count": 3,
#   "sandboxes": [
#     {
#       "sandbox": {
#         "sandboxId": "07E...",        # Required for all operations
#         "sandboxName": "mybox",       # Top-level field — use this for name lookup
#         "license": "Developer",
#         "isPendingActivation": false,
#         "canActivate": true,
#         "canDelete": true,
#         ...
#       }
#     }
#   ]
# }

IMPORTANT: Do NOT use Tooling API (SandboxInfo or SandboxProcess) for sandbox discovery. The mutation endpoints (activate/discard/delete) require the sandboxId (07E prefix) from the Connect REST API response, NOT the SandboxInfo.Id (0GQ prefix) or SandboxProcess.Id (0GR prefix).

NEVER use SOQL / `run_soql_query` / `sf data query` for sandbox lifecycle reads — status, inventory, details, license, or pending-activation state (e.g. a "get details / status / license / pending-activation for sandbox X" request). This data lives ONLY in the Connect REST API response (GET /sandbox/reports for name lookup, GET /sandbox/sandboxes/{07E-id} for ID lookup); there is no SObject that returns it correctly. (sf data query --use-tooling-api on SandboxInfo remains valid for the Create and Refresh flows in Operations 7 and 8, which look up the SandboxInfo record to mutate it — that is not a lifecycle read.) If a name lookup returns an empty inventory (count: 0), the sandbox does not exist — report an honest not_found; do NOT retry the lookup via SOQL and do NOT fabricate details.

Report the API result exactly as it comes back — never invent an error or a cause. A count: 0 response is a successful result meaning the sandbox is absent: record it directly as not_found with the endpoint and empty inventory as evidence. Do NOT reinterpret an empty list as an API failure. If the Connect REST API genuinely returns an error, capture that error body verbatim as the outcome — but do NOT speculate about why (e.g. "this must be a scratch org", "sandbox endpoints aren't supported here"). This endpoint does not report the org's edition or type, so any such explanation is a fabrication and must not appear in the output.

Discovery Patterns:

When user provides a sandbox NAME:

1. Call GET /sandbox/reports to get the full list
2. Iterate through sandboxes[] array
3. Check sandbox.sandboxName (top-level field) to find the matching sandbox
4. Extract sandbox.sandboxId from that record
5. Use the sandboxId in subsequent mutation operations

When user provides a sandboxId (07E prefix) directly:

1. Call GET /sandbox/sandboxes/{sandboxId} to verify it exists and check current status
2. Use the same sandboxId directly in the mutation endpoint — do NOT call /sandbox/reports

Required permission: ManageSandboxes

Operations

1. List Sandbox Inventory

Endpoint: GET /services/data/v66.0/sandbox/reports

Returns a list of all sandboxes with their IDs, names, statuses, and license types.

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

Response format:

{
  "count": 3,
  "sandboxes": [
    {
      "sandbox": {
        "sandboxId": "07E...",
        "sandboxName": "DevBox1",
        "license": "Developer",
        "isPendingActivation": false,
        "canActivate": true,
        "canDelete": true,
        "canDiscard": false
      }
    }
  ]
}