Developer Guide

Scratch Org Snapshot

Pilot, Winter ’19

@salesforcedocs
Last updated: November 9, 2018
 © Copyright 2000–2018 [Link], inc. All rights reserved. Salesforce is a registered trademark of
[Link], inc., as are other names and marks. Other marks appearing herein may be trademarks of
their respective owners.

2
CONTENTS

What Is a Scratch Org Snapshot? 5

How Snapshots Fit in the Development Life Cycle 5

How Snapshots Work 5

Get Started 6
User Permissions 6

Create a Snapshot 6
Check the Status of a Snapshot Creation 7
List all Snapshots 7
Delete a Snapshot 8

Create a Scratch Org Based on a Snapshot 8

Create the Scratch Org Definition File 8
Create the Scratch Org 8
Regain Your Scratch Org Limits Due to Socket Timeout Errors 9

Considerations for the Pilot 9

Important:​​ ​We provide Scratch Org Snapshot to selected customers through a pilot program that
requires agreement to specific terms and conditions. Scratch Org Snapshot is subject to change
and isn’t generally available unless or until Salesforce announces its general availability in
documentation or in press releases or public statements. We can’t guarantee general availability
within any particular time frame or at all. Make your purchase decisions only on the basis of
generally available products and features. All commands, parameters, and other features are
subject to change or deprecation at any time, with or without notice. Don't implement functionality
developed with these commands or tools.

3
4
What Is a Scratch Org Snapshot?
Often, configuring a scratch org so that it’s ready to use as a development and testing environment isn’t a
trivial process. It can require a combination of pushing source to a scratch org, seeding it with sample data,
installing a package or two, and then performing manual configuration and setup directly in the scratch org.
And then, poof, it expires, and you have to start all over again.

Enter the scratch org snapshot! Cue the super hero music.

A scratch org snapshot captures the state of a scratch org so that you can use it as a starting point to
create other scratch orgs.

How Snapshots Fit in the Development Life Cycle

Before we tell you more about how scratch org snapshots work and how to create them, it’s good to know
where they fit in to the development process and what they aren’t meant for.

A snapshot is a point-in-time copy of your scratch org, meaning, it’s static. If you continue to configure your
scratch org, you’ll need to take a new snapshot to reflect its current state.

You can only create a snapshot from a scratch org and, conversely, you can create only scratch orgs from a
scratch org snapshot. Snapshots have the same 200 MB data storage limit as scratch orgs. A snapshot isn’t
meant to replace source-driven development or a version control system. You’ll still follow development
best practices by externalizing and modularizing your project source.

Snapshots and scratch orgs don’t replace sandboxes for user acceptance testing. A snapshot is intended
to contain the static dependencies of a project, and not the entire happy soup of your production org.

How Snapshots Work

Here are some important things to know when using snapshots:

● Snapshots don’t expire. However, a snapshot created for a specific Salesforce release, let’s say
Winter ‘19, won’t work for the next release, Spring ‘19. You’ll need to manually delete your
snapshots at the end of a release. See ​Considerations for the Pilot​ for details regarding snapshots
created during the pilot.
● A snapshot captures the state of a scratch org at a point in time. If you make changes to the
scratch org that you want to include in a snapshot, you create a new snapshot (and delete the old
one if you want to use the same name).
● Snapshots are associated with the Dev Hub org. Therefore, the scratch orgs you create based on
the snapshot also belong to the same Dev Hub.
● Changing or deleting a scratch org has no effect on a snapshot.

5
Get Started
Prerequisites:

● Install Salesforce CLI​ or update to v44 of the ​salesforcedx​ plugin.

● Enable Dev Hub​ in your production org.
● Authorize​ your Dev Hub org.

Once you join the pilot, we’ll enable the Scratch Org Snapshot pilot feature in your production org. If you
need help, post on the ​Scratch Org Snapshot​ group in the Trailblazer community.

Next:​​ Give other users permission to create snapshots.

User Permissions
Dev Hub (production org) admins have the ability to create snapshots by default. To enable other users of
the production org to create snapshots:

1. In Setup, create a permission set.

2. From Object Settings, select ​Org Snapshots​​.
3. Under Object Permissions, click ​Edit​​, then select ​Read​​, ​Create​​, and ​Delete​​.
a. (Optional) Select ​View All​​ to allow users to see snapshots that other users create.
b. (Optional) Select ​Modify All​​ to allow users to delete snapshots that other users create.
c. Save your changes.
4. Click ​Manage Assignments​​, then ​Add Assignments​​.
5. Select the users, click ​Assign​​, then ​Done​​.

Create a Snapshot
Create a snapshot of a scratch org belonging to the pilot-enabled Dev Hub.

Note:​​ You can create up to 5 snapshots per Dev Hub daily, with a maximum of 5 active snapshots.

sfdx force:org:snapshot:create -n <name> -d <description> -o <scratch org username or

alias> -v <Dev Hub username>

Example:

sfdx force:org:snapshot:create -n dhsetup -d "Dreamhouse app" -o dreamhouse_scratch -v

DevHub

Your request is initially InProgress:

6
 ​Org Snapshot
=== Org
NAME VALUE
────────────────── ───────────────────
Id 0OoB00000004C98KAE
Snapshot Name dhsetup
Description Dreamhouse app
Status InProgress
Source Org 00D5600000097JOEAY
Expiration Date
Last Cloned Date
Last Cloned By
Created Date 2018-10-12 [Link]
Last Modified Date 2018-10-12 [Link]​9

Check the Status of a Snapshot Creation

Creating a snapshot can take a while. Use the snapshot name or ID to check its creation status.

sfdx force:org:snapshot:get -s <snapshot name or id> -v <Dev Hub username>

Using our previous example:

sfdx force:org:snapshot:get -s dhsetup -v DevHub

Once the status changes to Active, you can use the snapshot to create scratch orgs.

​Org Snapshot
=== Org
NAME VALUE
────────────────── ───────────────────
Id 0OoB00000004C98KAE
Snapshot Name dhsetup
Description Dreamhouse app
Status Active
Source Org 00D5600000097JOEAY
Expiration Date 2018-11-11
Last Cloned Date
Last Cloned By
Created Date 2018-10-12 [Link]
Last Modified Date 2018-10-12 [Link]

List all Snapshots

You can view all the snapshots in a Dev Hub that you have access to. If you’re an admin, you can see all
snapshots associated with the Dev Hub org. If you’re a user, you can see only your snapshots unless a Dev
Hub admin gave you View All permissions.

sfdx force:org:snapshot:list -v <Dev Hub username>

7
Delete a Snapshot
If you don’t need a snapshot anymore or run out of active snapshots, you can delete a snapshot. Dev Hub
admins can delete any snapshot, while users can delete only theirs unless a Dev Hub admin gave the user
Modify All permissions.

sfdx force:org:snapshot:delete -s <snapshot name> -v <Dev Hub username>

Create a Scratch Org Based on a Snapshot

Before you can create a scratch org based on a snapshot, you need to create a scratch org definition file
that references the snapshot. We recommend creating a definition file specifically for this purpose.

Create the Scratch Org Definition File

The scratch org definition is the blueprint for your scratch org. It’s likely that your snapshot includes all the
required features and settings to configure the scratch orgs created from it.

Important:​​ Use “snapshot” instead of “edition” in the scratch org definition file.

Using our Dreamhouse scratch org as an example, let’s create a scratch org definition file called
[Link]​ that contains only two entries: orgName and snapshot (name).

{
​"orgName"​: ​"Salesforce"​,
​"snapshot"​: ​"dhsetup"

Important:​​ In the pilot, you can’t specify features, settings, and org preferences in your snapshot scratch
org definition.

Create the Scratch Org

Now, you’re ready to create a scratch org based on your snapshot. It can take a little longer to create a
scratch org from a snapshot, so we suggest you also increase the ​--wait​ value so the command doesn’t
time out.

For example:

sfdx force:org:create -f config/[Link] -a dh_scratch -d 30 -w 10 -v

DevHub

If you get a socket timeout error, increase the ​--wait​ time, and try again.

Success! Development and testing with scratch orgs just got a whole lot easier.

8
Regain Your Scratch Org Limits Due to Socket Timeout Errors
Scratch org creation attempts count against your active scratch org limits although the scratch orgs aren’t
technically in an active state. To regain your limits, manually delete them from your Dev Hub.

1. Open your Dev Hub org.

2. From App Launcher, select ​Scratch Org Infos​​. Look for scratch orgs with a Status of ​New​​.
3. From the drop-down menu on the right, select ​Delete​​.

Considerations for the Pilot

1. Snapshots help with the setup steps but may not be fast to create. We will be addressing
performance in subsequent releases.
2. Snapshots will expire at the end of the pilot but will still appear in the list of snapshots. Users will
have to delete them manually in order to clean up the list.