Create a Sandbox Definition File

Before you can create a sandbox using Salesforce CLI, define the configuration for it in a sandbox definition file. The sandbox definition file is a blueprint for the sandbox. You can create different definition files for each sandbox type that you use in the development process.

Sandbox Configuration Values

Option Required? Description
activationUserGroupId No A reference to the ID of a public group of Salesforce users who can access the sandbox. The user who created the sandbox is added to the group by default.

You can specify either activationUserGroupId or activationUserGroupName but not both.

activationUserGroupName No The name of the public group of Salesforce users who can access the sandbox. The user who created the sandbox is added to the group by default.

You can specify either activationUserGroupId or activationUserGroupName but not both.

apexClassId No A reference to the ID of an Apex class that runs after each copy of the sandbox. Allows you to perform business logic on the sandbox to prepare it for use.

You can specify either apexClassId or apexClassName but not both.

apexClassName No The name of the Apex class that runs after each copy of the sandbox. Allows you to perform business logic on the sandbox to prepare it for use.

You can specify either apexClassId or apexClassName but not both.
autoActivate No If true, you can activate a sandbox refresh immediately.
copyArchivedActivities No Full sandboxes only. This field is visible if your organization has purchased an option to copy archived activities for sandbox. To obtain this option, contact Salesforce Customer Support.
copyChatter No If true, archived Chatter data is copied to the sandbox.
description No A description of the sandbox (1000 or fewer characters), which helps you distinguish it from other sandboxes.
historyDays No Full sandboxes only. Represents the number of days of object history to be copied in the sandbox.

Valid values:

  • -1, which means all available days
  • 0 (default)
  • 10
  • 20
  • 30
  • 60
  • 90
  • 120
  • 150
  • 180
licenseType Yes (for sandbox creation) Valid values are Developer, Developer_Pro, Partial, and Full.

You can specify only one of these options: licenseType, sourceSandboxName, or sourceId.
sandboxName Yes A unique alphanumeric string (10 or fewer characters) to identify the sandbox. You can’t reuse a name while a sandbox is in the process of being deleted.
sourceId Yes (for sandbox cloning) A reference to the ID of the sandbox being cloned.

You can specify only one of these options: licenseType, sourceSandboxName, or sourceId.
sourceSandboxName Yes (for sandbox cloning) Name of the sandbox being cloned.

You can specify only one of these options: licenseType, sourceSandboxName, or sourceId.
templateId Yes (for Partial sandboxes) Optional for Full sandboxes. Not available for Developer and Developer Pro sandboxes.

A reference to the sandbox template as identified by the 15-character ID beginning with 1ps in the URL when viewing a sandbox template in a browser. A sandbox template lets you select which objects to copy in a sandbox.

Sample Sandbox Definition File

Although you can place the sandbox definition file anywhere, we recommend keeping it in your Salesforce DX project in the config directory. When naming the file, we suggest providing a descriptive name that ends in sandbox-def.json, for example, developer-sandbox-def.json.

Here's a sample definition file for creating a sandbox:

{
     "sandboxName": "dev1",
     "licenseType": "Developer"
}

Here's a sample definition file for cloning a sandbox:

{
     "sandboxName": "dev1clone",
     "sourceSandboxName": "dev1"
}