in implementation guides ~ read.
Deploy Sandboxes

Deploy Sandboxes

DOWNLOAD

First things first !
To download this implementation guide, click the download button below.
If you need more information about the implementation guide, you can read the Table of Contents below.

Download

Sandboxes Staging
Environments for Customizing
and
Testing
Salesforce Spring

salesforcedocs
Last updated March

Copyright salesforcecom inc All rights reserved Salesforce is a registered trademark of salesforcecom inc

as are other names and marks Other marks appearing herein may be trademarks of their respective owners

CONTENTS

Sandboxes Staging Environments for Customizing and Testing
When to Use a Sandbox
Sandbox Setup Considerations
Create Clone or Refresh a Sandbox
Manage Your Sandboxes
Manage Your Sandboxes Programmatically
Deploy Your Changes
Secure Your Sandbox Data with Salesforce Data Mask

Index

SANDBOXES STAGING ENVIRONMENTS FOR

CUSTOMIZING AND TESTING

Want to customize your organization in a staging environment where you can test changes without affecting your production organization
or its users Want to have an organization that users can log into and test new features before theyre productionready Or maybe you
just want to log into a Salesforce organization for training or development that mirrors your production organization

IN THIS SECTION

When to Use a Sandbox
Sandboxes create copies of your Salesforce org in separate environments Use them for development testing and training without
compromising the data and applications in your production org
Sandbox Setup Considerations
Sandbox behavior is similar to a Salesforce production org but important differences affect how you configure and test a sandbox
org
Create Clone or Refresh a Sandbox
Create a sandbox to use for development testing and training Clone a sandbox to copy its data and metadata into another sandbox
Refresh an existing sandbox to update its contents
Manage Your Sandboxes
In Setup enter Sandboxes in the Quick Find box then select Sandboxes Sandboxes displays the available sandboxes that
you purchased and a list of your sandboxes in use
Manage Your Sandboxes Programmatically

Use Salesforce CLI to authorize in to create and clone sandboxes Traditionally admins create and manage sandboxes through the

Setup UI But we realize that many admins and developers want the ability to create and manage their development and testing

environments programmatically and to automate their CI processes Salesforce CLI enables you to do both

Deploy Your Changes
Migrate metadata changes between Salesforce orgs by using the deployment tools available in Setup
Secure Your Sandbox Data with Salesforce Data Mask
Salesforce Data Mask is a powerful data security resource for Salesforce admins and developers Instead of manually securing data
and access for sandbox orgs admins can use Data Mask to automatically mask the data in a sandbox Data Mask enables admins

and developers to mask sensitive data in sandboxes such as Personally Identifiable Information PII or sales revenue

When to Use a Sandbox
Sandboxes create copies of your Salesforce org in separate environments Use them for development testing and training without
compromising the data and applications in your production org
Salesforce offers sandboxes and a set of deployment tools so you can
Isolate customization and development work from your production environment until youre ready to deploy changes
Test changes against copies of your production data and users
Provide a training environment
Coordinate individual changes into one deployment to production

Sandboxes Staging Environments for Customizing and
Testing

Sandbox Types and Templates

Whether youre an administrator adding features to an organization a solo developer writing code or a team of developers working to
enhance your organization you should work with the right tools in the right environment to build and deploy change successfully to
your production organization For a broad overview of the development process and recommendations for organizing your work see
the Application Lifecycle and Development Models module on Trailhead

IN THIS SECTION

Sandbox Types and Templates
Sandboxes are isolated from your production org so operations that you perform in your sandboxes dont affect your production
org
Sandbox Licenses and Storage Limits by Type

A sandbox is a copy of your organization in a separate environment that you can use for a variety of purposes such as testing and

training Sandboxes are completely isolated from your Salesforce production organization The operations you perform in your
sandboxes dont affect your Salesforce production organization You can create different sandbox environments for your org
depending on your needs for storage copy configuration and frequency of refresh

SEE ALSO

Sandbox Types and Templates
Deploy Your Changes
Choose Your Tools for Developing and Deploying Changes

Sandbox Types and Templates
Sandboxes are isolated from your production org so operations that you perform in your sandboxes
dont affect your production org

EDITIONS

From Setup enter Sandboxes in the Quick Find box then select Sandboxes to view and
manage your existing sandboxes or create new ones

Available in both Salesforce
Classic not available in all
orgs and Lightning
Experience

Sandbox Types
Developer Sandbox

A Developer sandbox is intended for development and testing in an isolated environment A

Developer Sandbox includes a copy of your production orgs configuration metadata
Developer Pro Sandbox

A Developer Pro sandbox is intended for development and testing in an isolated environment

and can host larger data sets than a Developer sandbox A Developer Pro sandbox includes a

copy of your production orgs configuration metadata Use a Developer Pro sandbox to handle
more development and quality assurance tasks and for integration testing or user training
Partial Copy Sandbox

A Partial Copy sandbox is intended to be used as a testing environment This environment

includes a copy of your production orgs configuration metadata and a sample of your
production orgs data as defined by a sandbox template Use a Partial Copy sandbox for quality
assurance tasks such as user acceptance testing integration testing and training

Available in Professional
Enterprise Performance
Unlimited and
Databasecom Editions

USER PERMISSIONS

To view a sandbox
View Setup and
Configuration
To create refresh activate
and delete a sandbox
Manage Sandbox

Sandboxes Staging Environments for Customizing and
Testing

Sandbox Types and Templates

Full Sandbox

A Full sandbox is intended to be used as a testing environment Only Full sandboxes support performance testing load testing and

staging Full sandboxes are a replica of your production org including all data such as object records and attachments and metadata
The length of the refresh interval makes it difficult to use Full sandboxes for development
We recommend that you apply a sandbox template so that your sandbox contains only the records that you need for testing or
other tasks
When you create a Full sandbox you also have to decide how much field tracking history and Chatter activity to include
The default is to omit field tracking but you can include up to days of field tracking If you track field history for many objects
in your production org specify fewer days to avoid generating an excessive amount of data
Chatter activity data can be extensive which can add a significant amount of time to your Full sandbox copy
Limit the amount of field history that you copy and copy your Chatter data only if you need it for your testing use cases

Sandbox Templates Tab
If you have purchased a license for Partial Copy or Full sandboxes this tab lists any templates you have created
Create a Sandbox Data Template create a sandbox from a template edit or delete a template or click the template name for more
information For more information about creating a Sandbox Data Template see Create or Edit Sandbox Templates on page

Sandbox History Tab
This tab displays a log of your sandbox creation and a history of refreshes including when sandbox were created and who created them
The Sandbox History tab shows the sandboxes you created or refreshed within the last year up to entries The tab lists sandboxes
with the most recent activity the ones created or refreshed first
This tab provides information only To view or edit an existing sandbox use the Sandbox tab

Sandbox Licenses
You purchase licenses for each sandbox type and can purchase multiple licenses of each type Sandbox licenses are hierarchical Specifically
the following table shows the type of sandbox you can create with each license
Full Sandbox
license

Partial Copy
Sandbox license

Developer Pro
Sandbox license

Allows you to create
Developer sandbox type
Developer Pro sandbox type
Partial Copy sandbox type
Full sandbox type

License stages are
Available
The displayed value represents the number of sandbox that youve purchased but havent used

Developer
Sandbox license

Sandboxes Staging Environments for Customizing and
Testing

Sandbox Types and Templates

In use
The displayed value represents the number of sandboxes that youve purchased and used
Note If you dont see a sandbox option or need licenses for more sandboxes contact Salesforce to order sandboxes for your org
When your sandbox licenses expire your existing sandboxes are subject to certain restrictions See Unlock a Sandbox on page for
resolution of license expiration issues

Understanding Sandbox Refresh Intervals
The refresh interval for each sandbox environment is calculated from when the actual sandbox copying process begins The sandbox
status changes from Pending to Processing at the start of copying
If other sandbox copy requests were made before yours your sandbox sometimes remains in the Pending status for some time The
refresh interval timer for your sandbox doesnt start until your request leaves this state

IN THIS SECTION

Create or Edit Sandbox Templates
Sandbox templates control which data is copied into a sandbox

SEE ALSO

Create a Sandbox
Sandbox Licenses and Storage Limits by Type
Unlock a Sandbox

Create or Edit Sandbox Templates
Sandbox templates control which data is copied into a sandbox

EDITIONS

Sandbox templates allow you to pick specific objects and data to copy to your Full or Partial Copy
sandbox to control the size and content of each sandbox Sandbox templates are only available for
use with Full or Partial Copy sandboxes
When you create a sandbox template you select the object data standard and custom to copy
during the creation or refresh of a sandbox
The sandbox template editor understands the relationships that are defined in your Salesforce orgs
object schema Some objects are included even before youve selected anything because theyre
required in any org As you select objects to copy the editor ensures that the associated required
objects are added To see which related objects are required by an object select it in the Object
table Required objects are displayed in the Required Objects column
As you change the schema of the objects in your org Salesforce updates the template by adding

or subtracting related required objects For example if Object A is a master of Object B and you

add Object B to a template Salesforce requires Object A in the template and adds Object A

Note Full and Partial Copy sandboxes can support asset files along with other content
entities Make sure to select Content Body in the template
From Setup enter Sandboxes in the Quick Find box select Sandboxes then click the
Sandbox Templates tab

Available in both Salesforce
Classic not available in all
orgs and Lightning
Experience
Available in Professional
Enterprise Performance
Unlimited and
Databasecom Editions

USER PERMISSIONS

To view a sandbox
View Setup and
Configuration
To create refresh activate
and delete a sandbox
Manage Sandbox

Sandboxes Staging Environments for Customizing and
Testing

Sandbox Licenses and Storage Limits by Type

Click New Sandbox Template or click Edit next to an existing template you want to modify
Enter a name and description for the sandbox template
To add objects to the template select the checkbox for each object you want from the available Objects list
The Object Details section shows you the objects to be added automatically with the one youve selected
To remove objects from the template deselect the checkbox for the object in the available Objects list
If you remove an object you previously selected dependent objects you didnt explicitly select are removed If you attempt to remove
an object with dependent objects you receive a warning requesting a confirmation of the removal After you confirm your choice
those objects are also removed
Click Save
To understand how to use a Sandbox template during sandbox creation or refresh see Create a Sandbox on page
To understand how a Sandbox template is used by the sandbox copy engine to create a Full or Partial Copy sandbox see Sandbox
Licenses and Storage Limits by Type on page
Warning If you modify your object schema your sandbox templates could be altered to include objects that are required by
relationships If you make a change to a required relationship in your object schema review your sandbox templates to ensure
that objects that you expect to be selected are still selected

SEE ALSO

Create a Sandbox
Sandbox Licenses and Storage Limits by Type
Sandbox Types and Templates

Sandbox Licenses and Storage Limits by Type

A sandbox is a copy of your organization in a separate environment that you can use for a variety

of purposes such as testing and training Sandboxes are completely isolated from your Salesforce
production organization The operations you perform in your sandboxes dont affect your Salesforce
production organization You can create different sandbox environments for your org depending
on your needs for storage copy configuration and frequency of refresh
Each type has different features to support the activities its designed for
Table Sandboxes Available Per Edition
Sandbox Type

Professional Enterprise
Edition
Edition

Unlimited
Edition

Performance
Edition

Developer
Sandbox

Developer Pro
Sandbox
Partial Copy
Sandbox

Not Available

Full Sandbox

Not Available

EDITIONS

Available in both Salesforce
Classic not available in all
orgs and Lightning
Experience
Available in Professional
Enterprise Performance
Unlimited and
Databasecom Editions

If you need licenses for more sandboxes contact Salesforce to order sandboxes for your organization

Sandboxes Staging Environments for Customizing and
Testing

Sandbox Licenses and Storage Limits by Type

Note You can buy additional Developer Pro sandboxes for any edition or Partial and Full sandboxes for Enterprise Unlimited
and Performance editions
Developer Sandboxes arent available for purchase but are bundled with addon sandboxes of other types
The Developer Pro Sandbox addon is bundled with Developer Sandboxes
The Partial Copy Sandbox addon is bundled with Developer Sandboxes
The Full Sandbox addon is bundled with Developer Sandboxes
Note You can match provisioned licenses in production to your sandbox org without having to refresh your sandbox This process
updates sandbox license counts to match the counts in production The process also adds licenses that are in production but not
in sandbox and deletes licenses that arent in production
Table Sandbox Feature Quick Reference
Sandbox Type

Refresh Interval

Storage Limit

Whats Copied

Sandbox Templates

Developer Sandbox

day

Data storage MB

Metadata only

Not available

Metadata only

Not available

Metadata and sample
data

Required

Same as your production Metadata and all data
org

Available

File storage MB

Developer Pro Sandbox

day

Data storage GB

File storage GB

Partial Copy Sandbox

days

Data storage GB

File storage Same as
your production org

Full Sandbox

days

Note Sandboxes dont send email notifications when storage limits are reached However if you reach the storage limit of your
sandbox you cant save new data in it To check your storage limits from Setup enter Storage Usage in the Quick Find box
then select Storage Usage

SEE ALSO

Create a Sandbox
Create or Edit Sandbox Templates
Sandbox Setup Considerations

Sandboxes Staging Environments for Customizing and
Testing

Sandbox Setup Considerations

Sandbox Setup Considerations
Sandbox behavior is similar to a Salesforce production org but important differences affect how
you configure and test a sandbox org

EDITIONS

IN THIS SECTION

Available in both Salesforce
Classic not available in all
orgs and Lightning
Experience

Servers and IDs
Sandbox and production orgs have unique org IDs The sandbox copy engine creates an org
as part of each creation and refresh request
Users and Contacts
User information is included in a sandbox copy or refresh for all sandbox types

Available in Professional
Enterprise Performance
Unlimited and
Databasecom Editions

Email Deliverability
New and refreshed sandboxes have the default email deliverability setting System email only

USER PERMISSIONS

Configuring Full Sandboxes
When you create or refresh a full sandbox you can configure it to determine what data is copied
Minimizing the amount of data you include speeds up your sandbox copy

To view a sandbox
View Setup and
Configuration

Sandbox Access Considerations
Consider the following access changes before you create a sandbox so that sandbox users can

make full use of the sandbox environment for development and UAT testing

To create refresh activate
and delete a sandbox
Manage Sandbox

Customization and Data Changes
Customizations and data changes in your production org arent reflected in your sandboxes
Product and Service Exclusions
Some products and services are enabled in production orgs and disabled by default in sandboxes Some can be reenabled while
others cannot
Other Service Differences
Sandbox behavior is similar to a Salesforce production org but important differences affect how you configure and test a sandbox
org

SEE ALSO

Knowledge Article Match production and sandbox licenses without a sandbox refresh
Apex Developer Guide SandboxPostCopyInterface
Create a Sandbox
Sandbox Types and Templates
Sandbox Licenses and Storage Limits by Type
Unlock a Sandbox

Sandboxes Staging Environments for Customizing and
Testing

Servers and IDs

Servers and IDs
Sandbox and production orgs have unique org IDs The sandbox copy engine creates an org as part
of each creation and refresh request

EDITIONS

The org ID of your sandbox changes each time your sandbox is refreshed Salesforce inserts the

new value in any place the org ID is used such as text values and metadata

Available in both Salesforce
Classic not available in all
orgs and Lightning
Experience

To find the ID of the org that youre logged in to from Setup enter Company Information

in the Quick Find box then select Company Information A script or process such as a test

script or WebtoLead that depends on a hardcoded org ID must use the current ID for the

sandbox When you deploy your changes to a production org update the scripts or processes

with the production org ID

Salesforce creates sandbox orgs on several instances When a sandbox is created or refreshed
Salesforce selects an instance for your sandbox so your sandboxes sometimes appear on
different instances and have different URLs
When data is copied to a sandbox object IDs for records are copied Object IDs are unique

identifiers for all objectsthe same as the ID Field Type in the developer API After being copied

however object IDs dont synchronize between the production org and sandbox The sandbox
and its corresponding production org act as independent orgs Object data and corresponding
object IDs that are created in the production org after the sandbox is created or refreshed dont
synchronize into the sandbox The sandbox has the same behaviornew objects that are
created in the sandbox arent synchronized back to the production org

Available in Professional
Enterprise Performance
Unlimited and
Databasecom Editions

USER PERMISSIONS

To view a sandbox
View Setup and
Configuration
To create refresh activate
and delete a sandbox
Manage Sandbox

Users and Contacts
User information is included in a sandbox copy or refresh for all sandbox types
Because all Salesforce usernames must be unique and reference a single org usernames are
modified to ensure uniqueness as they are copied
For each username the copy process does the following
First the sandbox name is appended to the username For example the username
useracmecom for a sandbox named test becomes useracmecomtest
If the resulting username is not unique a second modification is performed in which some
characters and digits are prepended to the modified username This second modification
results in a username such as xVquseracmecomtest

EDITIONS

Available in both Salesforce
Classic not available in all
orgs and Lightning
Experience
Available in Professional
Enterprise Performance
Unlimited and
Databasecom Editions

When you log in with the modified username you log in to the corresponding sandbox
The copy process doesnt copy Contact data to Developer or Developer Pro sandboxes Therefore
Customer Portal users arent copied However the copy process does copy the Customer Portal
licenses so you can create Customer Portal users in Developer or Developer Pro sandboxes

USER PERMISSIONS

To view a sandbox
View Setup and
Configuration

When you create or refresh a sandbox user email addresses are modified so that production
users dont receive automatically generated email messages from the sandbox User email
To create refresh activate
addresses are appended with invalid This modification ensures that the system ignores
and delete a sandbox
these email addresses For example a user email of
Manage Sandbox
awheeleruniversalcontainerscom in production becomes
awheeleruniversalcontainerscominvalid when migrated to sandbox If
you want sandbox users to receive automatically generated emails as part of testing you can correct the email addresses while

Sandboxes Staging Environments for Customizing and
Testing

Email Deliverability

logged in to the sandbox Return email addresses set in users Email Settings in production arent appended with invalid in
the sandbox
Warning Sandboxes change Salesforce user email addresses but dont change other email addresses in Salesforce such as
email addresses in contact records To avoid sending unsolicited email manually invalidate or delete all email addresses in
your sandboxes that dont belong to users of the sandbox When testing outbound email change contact email addresses to
the addresses of testers or an automated test script
Each sandbox users account email must be verified before that users account can send email from Salesforce

Email Deliverability
New and refreshed sandboxes have the default email deliverability setting System email only
To configure email deliverability settings in the sandbox org from Setup enter Deliverability
in the Quick Find box then select Deliverability If editable set the access level in the Access to
Send Email section If Salesforce has restricted your orgs ability to change this setting you cant
edit the access level
No accessPrevents all outbound email to and from users
System email onlyAllows only automatically generated emails such as new user and password
reset emails
All emailAllows all types of outbound email Default for new nonsandbox orgs
Tip The System email only setting is especially useful for controlling email sent from
sandboxes so that testing and development work doesnt send test emails to your users
Newly created sandboxes default to System email only
Sandboxes created before Spring default to All email

EDITIONS

Available in both Salesforce
Classic not available in all
orgs and Lightning
Experience
Available in Professional
Enterprise Performance
Unlimited and
Databasecom Editions

USER PERMISSIONS

To view a sandbox
View Setup and
Configuration
To create refresh activate
and delete a sandbox
Manage Sandbox

Sandboxes Staging Environments for Customizing and
Testing

Configuring Full Sandboxes

Configuring Full Sandboxes
When you create or refresh a full sandbox you can configure it to determine what data is copied
Minimizing the amount of data you include speeds up your sandbox copy

EDITIONS

The Object History Case History Content Version History and Opportunity History options
enable you to select the length of history to copy from your production org to your sandbox
You can copy from to days of history in day increments The default is days

Available in both Salesforce
Classic not available in all
orgs and Lightning
Experience

By default Chatter data isnt copied to your sandbox Chatter data includes feeds and messages
Select Copy Chatter Data if you want to include it
The setup audit trail history of your production org isnt copied to your sandbox The audit trail
for your sandbox org starts when you begin to use it
Archived activities tasks and events that arent available because theyre over a year old and
user password history arent copied
Note Dont increase the default selections unless special circumstances require it Large
amounts of data can significantly lengthen the time it takes to copy your sandbox

Available in Professional
Enterprise Performance
Unlimited and
Databasecom Editions

USER PERMISSIONS

To view a sandbox
View Setup and
Configuration
To create refresh activate
and delete a sandbox
Manage Sandbox

Sandbox Access Considerations
Consider the following access changes before you create a sandbox so that sandbox users can

make full use of the sandbox environment for development and UAT testing

EDITIONS

Access changes to consider for sandbox users

Available in both Salesforce
Classic not available in all
orgs and Lightning
Experience

A sandbox refresh deletes and recreates the sandbox as a copy of the production org This

process reverses any manual access changes you made If you created sandboxonly users
then they no longer exist Other users profile and permissions revert to their values in the
production org After a refresh make any access changes in the new copy
You can create users in your production org that are inactive and then activate them in a
sandbox This method is a good way to create a user that has the appropriate permissions
to develop in a sandbox
Many development and testing tasks require the Modify All Data permission If your
developers dont have that permission in the production org increase their permissions in
the sandbox Exercise caution when granting this permission in sandbox orgs that contain
sensitive information copied from production for example social security numbers
Users added in a production org after creating or refreshing a sandbox dont have access
to the production org instances related sandboxes To create users in a sandbox log in as
the administrator on the sandbox org and create them in the sandbox instance
You can create users for sandbox development but these new users count against the
number of licensed users in your org To reduce your license count you can disable
production users who dont need access to the sandbox before you create or refresh a
sandbox

Always log in to your sandbox org using the httpstestsalesforcecom login URL

Available in Professional
Enterprise Performance
Unlimited and
Databasecom Editions

USER PERMISSIONS

To view a sandbox
View Setup and
Configuration
To create refresh activate
and delete a sandbox
Manage Sandbox

Sandboxes Staging Environments for Customizing and
Testing

Customization and Data Changes

Remember to log in using the modified username as described in Users and Contacts on page

If using the API after you log in use the redirect URL that is returned in the loginResult object for subsequent access This URL reflects

the instance on which the sandbox is located and the appropriate server pool for API access

Sandbox copies are made with federated authentication with SAML disabled Configuration information is preserved except the

value for Salesforce Login URL Salesforce Login URL is updated to match your sandbox URL for example

httpsyourInstancesalesforcecom after you reenable SAML To enable SAML in the sandbox from Setup

enter Single SignOn Settings in the Quick Find box then select Single SignOn Settings Then click Edit and select

SAML Enabled For more information about configuring SAML settings see Configure SAML Settings for Single SignOn

Customization and Data Changes
Customizations and data changes in your production org arent reflected in your sandboxes

EDITIONS

To incorporate the most recent customizations made to your org create or refresh a sandbox
You can only add edit or delete Apex using the Salesforce user interface in a Developer Edition
or sandbox org In a Salesforce production org you can only change Apex by using the

compileAndTestAPI call

If your sandbox is the same version as Salesforce AppExchange you can
Install and deploy apps from Salesforce AppExchange in your sandbox
Publish apps from your sandbox to Salesforce AppExchange
Publishing managed packages from a Lightning Platform Sandbox is not advised as
refreshing or deleting the sandbox prevents any revisions to that managed package
The version of your sandboxes can differ from Salesforce AppExchange around the time of a
Salesforce release Check the logo in the upper left corner of your sandbox home page for
version information
If your org uses quote templates and you create a Developer Pro sandbox you cant open
templates that contain TextImage fields for editing within the sandbox
If your production org uses an image in quote templates or service reports and you copy the
org to your sandbox the image path is not correct and the image appears as a broken link To
display the image reinsert it from the correct location on your sandbox

Available in both Salesforce
Classic not available in all
orgs and Lightning
Experience
Available in Professional
Enterprise Performance
Unlimited and
Databasecom Editions

USER PERMISSIONS

To view a sandbox
View Setup and
Configuration
To create refresh activate
and delete a sandbox
Manage Sandbox

Big Object records are not copied to a sandbox The sandbox contains the Big Object definition but none of the records associated
with the Big Object

***