Sandbox Management

Working with sandboxes is a click-heavy process. A stale sandbox is an easy way to accidentally introduce bugs into your release process. If you want to refresh several, or if you want to create a process for regular refreshes the Salesforce CLI can help.

Prerequisites

Org Authorizations

In order to perform these commands you will need to have authorized your production org with the Salesforce CLI with a user ID that has permissions to work with the setup menu with the "Customize Application" permission.

To mitigate risks in this instance, you may want to make this user have reduced data access and visibility permissions.

Objects Involved

• SandboxInfo: Metadata about each individual sandbox (name, description, license, etc.)
• SandboxProcess: Stores sandbox status data during the async refresh process

Note these are all tooling API objects, requiring the -t flag.

Relevant SFCLI Commands

sfdx force:data:record:create
sfdx force:data:record:update
sfdx force:data:soql:query

Recipes

List Sandboxes Status

List statuses for the 20 most recent sandboxes associated with the org requested.

> sfdx force:data:soql:query -t -u *OrgUserOrAlias* -q 'SELECT SandboxName,Status,CopyProgress,AutoActivate,SandboxOrganization,StartDate FROM SandboxProcess ORDER BY ActivateDate DESC LIMIT 20'

SOQL Query commands can be verbose to type, so let's break down the SOQL Query for better understanding

SELECT SandboxName,  <--- which fields to display data from
       Status,
       CopyProgress,
       AutoActivate,
       SandboxOrganization,
       StartDate 
FROM SandboxProcess   <--- the object to query
ORDER BY ActivateDate DESC   <--- show the most recent records at the top
LIMIT 20   <--- Only show us the first 20

Create Sandbox

Kick off the sandbox creation process.

> sfdx force:data:record:create -t -u *OrgUserOrAlias* -s SandboxInfo -v "LicenseType=DEVELOPER AutoActivate=true SandboxName=MySandbox Description='This is my new sandbox'"

The -v flag is for the values you wish to set for the fields in the new record. Wrap the whole set of field names/values in double quotes. For longer values with special characters use single quotes.

Permitted values for LicenseType are: DEVELOPER, DEVELOPER_PRO, PARTIAL, FULL

These are a minimal subset of the fields you might want to populate when creating a new sandbox. The full list of field for creating a new sandbox are found in the tooling API documentation.

Refresh Sandbox

To refresh an existing sandbox, you must invoke an update on the sandbox and at a minimum specify a license type.

> sfdx force:data:record:update -t -u *OrgUserOrAlias* -s SandboxInfo -w SandboxName=MySandbox -v "LicenseType=DEVELOPER AutoActivate=true SandboxName=MySandbox Description='This is my refreshed sandbox'"

See notes above in Create Sandbox for allowed license types and other fields to set.

Get Single Sandbox Status

To get the status of a single sandbox we will use SOQL again. This is similar to the list operation above, only we will limit to the most recent sandbox that matches the name we are querying for. This is tricky, requiring changing the where portion of the query to your own sandbox name.

> sfdx force:data:soql:query -t -u *OrgUserOrAlias* -q "SELECT SandboxName,Status,CopyProgress,AutoActivate,LicenseType,SandboxOrganization,StartDate FROM SandboxProcess WHERE SandboxName = 'MySandbox' ORDER BY ActivatedDate DESC LIMIT 1"

To break down the SOQL again, specifically to more clearly identify what needs to be changed:

SELECT SandboxName,  
       Status,
       CopyProgress,
       AutoActivate,
       LicenseType,
       SandboxOrganization,
       StartDate 
FROM SandboxProcess 
WHERE SandboxName = 'MySandbox' <--- change the value between these quotes to your sandbox
ORDER BY ActivatedDate DESC 
LIMIT 1