When developing on Salesforce, you can use scratch orgs, sandboxes, or Developer Edition orgs as your development environments. Choosing the right Salesforce org for the specific job is crucial. See the Salesforce blog on choosing the right Salesforce org for the right job for more details.

But optimizing your developer environments can significantly enhance productivity. In this post, we’ll explore how to use Scratch Org Shapes and Snapshots to create the ideal org environment for your projects.

Why choose a scratch org

Scratch orgs are preferred for their quick creation, configurability, and disposability, allowing developers to emulate different Salesforce editions and features. They enable efficient change tracking, seamless code deployment, and experimentation without impacting production environments. Scratch Org Shapes and Snapshots are new tools to create scratch orgs.

Before we delve into the details, let’s get familiar with the key terms and concepts of Salesforce DX (Salesforce Developer Experience) related to scratch orgs.

• Dev Hub is a Salesforce DX feature that lets you create and manage scratch orgs, unlocked packages, and second-generation managed packages. You can enable Dev Hub in a production org or a separate org.
• Salesforce CLI is a command-line interface that provides a collection of commands to simplify development and automations with your Salesforce org. It has commands to manage orgs, create and install packages, create Apex classes, etc. It is available for Mac, Windows, and Linux operating systems.
• Scratch org definition file is a blueprint for a scratch org. It holds the settings and configuration options associated with a scratch org. It mimics the shape of an org that you use in the development lifecycle, such as sandbox, packaging, or production.

Creating a scratch org

You can build a scratch org with your own definition file to meet basic project needs. However, the scratch org definition file can become complex when replicating the features from a production environment.

Let’s take a look at how to generate a scratch org from an existing environment and address common developer challenges step-by-step. There are two effective methods for configuring scratch orgs:

1. Creating a scratch org based on an org shape: Overcome the limitations of standard scratch org configurations by creating an org that mirrors the shape of an existing production org.
2. Creating a scratch org by capturing scratch org snapshots: Master the process of taking snapshots of your scratch org to back up its data and metadata, enabling easy creation of multiple versions for different tasks.

Creating a scratch org based on an org shape

You can create a scratch org that mirrors the shape and features of an existing production org using org shape. By capturing the shape of the org, you can spin up scratch orgs based on it, which is useful for standardizing configurations across teams. First, let’s get familiar with the common terminology used in org shape:

• Source org: The org whose shape you want to capture
• Dev Hub org: The org where you manage the scratch orgs
• Scratch org definition file: The file where the org shape is captured

You can capture the org shape, which includes the features, settings, edition, licenses, and limits of the source org, saving the manual effort of adding these details to the scratch org definition file. Once captured, you can create a scratch org using this org shape. If needed, you can also add more features and settings to the scratch org definition file to include additional functionality not present in the source org.

Let’s look at the steps to create a scratch org based on an org shape. Each step shown in the illustration is further elaborated.

Step 1: Enable Org Shape in the source org

• From Setup, search Scratch Orgs and toggle Enable Org Shape for Scratch Org.
• Associate it with a Dev Hub org (if Dev Hub is enabled in a different org). You can do that by entering the first 15 digits of the org ID of the Dev Hub org as shown below.

Step 2: Enable Org Shape in the Dev Hub org

If your Dev Hub org is different from the source org, you should also enable Org Shape in the Dev Hub org.

Step 3: Assign Org Shape permissions to users

In the Dev Hub org, assign Org Shape permissions to the users who plan to create org shapes, or create scratch orgs based on an org shape. Admins can create org shapes by default.

Step 4: Authorize source and Dev Hub org

Authorize both your Dev Hub org and the source org using the CLI command sf auth web login --alias. For example, if your Dev Hub org alias is my-dev-hub and the source org alias is my-source-org, your commands look like below.

sf auth web login —alias my-dev-hub
sf auth web login —alias my-source-org

Step 5: Create the org shape

Create the org shape for the source org using the CLI command sf org create shape --target-org <source org username/alias>. For example, if your source org alias is my-source-org, your command looks like below.

sf org shape create —target-org my-source-org

Note: The create shape command kicks off an asynchronous process to create the org shape. You can check the status of the org shape creation using the command sf org shape list. The status is changed from InProgress to Active once created. Only one shape can be active at a time for a source org. If you run the create shape command again on the same source org, only the latest shape is made active and the earlier shapes become inactive.

Step 6: Create a scratch org

Create a scratch org from an org shape by specifying the source org ID. For example, if the org ID of my-source-org is 00DB1230000Ifx5. The command looks like below.

sf org create scratch --source-org 00DB1230000Ifx5

You can create a scratch org based solely on the source org shape as shown above. But, If you want to add more features and settings, you can do it by using the scratch org definition file. Let’s say you want to additionally add Communities and Service Cloud features, then create a scratch org definition like below.

Important Note: In the scratch org definition file, replace edition option with sourceOrg and use the first 15 characters of the source org Id as shown above.

You can now create the scratch org by specifying the path to your scratch org definition file. An example command looks like this below.

sf org create scratch -f config/project-scratch-def.json -a my-scratch-from-shape

The sequence of steps to create scratch org from shapes using scratch org definition file is illustrated below.

Check out our video to see how you can use Scratch Org Shapes.

Key considerations

• You can create an org shape from Developer, Group, Professional, Unlimited, and Enterprise editions.
• You can not create an org shape from scratch orgs and sandboxes.
• Org shapes are specific to a release. Be sure to recreate the org shape after the source org is upgraded to the new Salesforce release.
• Check what’s included and what’s not included in the org shape.
• Some features and settings are not captured by the org shape due to security or legal reasons, for example Chatbot, DevOpsCenter, MultiCurrency, PersonAccounts. The workaround is to add them to the scratch org definition file.
• The Org Shape feature accepts only 15-character org IDs. The workaround is to use only the first 15 characters of a standard 18-character org ID.

Scratch Org Shapes specialize in capturing and replicating configuration settings and features from a source org, ensuring consistent environments without including data. They are ideal for standardizing scratch org configurations across teams. For scenarios requiring the complete state of an org, including both data and metadata, Scratch Org Snapshots provide a solution.

Let’s now delve into Scratch Org Snapshots.

Creating a scratch org by capturing scratch org snapshots

You can create a copy of your scratch org at a particular point in time, which is called a snapshot. This copy (snapshot) includes packages, features, limits, licenses, and most importantly, it includes data, metadata, and installed packages at a given point in time. This is useful for rapid testing and development.

Getting a scratch org ready with all your project’s dependencies can be a real hassle. You have to deploy the metadata, add sample data, install packages, and then do a bunch of manual tweaks in the scratch org. And just when you have everything set up, the scratch org expires, and you have to start all over again. But with scratch org snapshots, you can skip all that. You can quickly replicate a scratch org with everything you need, making the whole process way easier.

Let’s look at how we can create and use scratch org snapshots.

Step 1: Enable Scratch Org Snapshots in the Dev Hub org

From Setup, search Scratch Orgs and toggle Enable Scratch Org Snapshots. A snapshot must belong to the Dev Hub org that you’re using to create the scratch orgs.

Step 2: Assign permissions to non-admin snapshot users

Provide the user with permissions to create snapshots. All non-admin Scratch Org Snapshots users should be assigned a license and access to the required scratch org and snapshot objects.

Note: Admins can create and manage snapshots by default.

Step 3: Create the scratch org snapshot

Create a scratch org snapshot using the sf org create snapshot command with a snapshot name. A snapshot name can have a maximum length of 15 characters.

For example, let’s create a name, dhsnapshot, using the scratch org with the alias dreamhouse-org, and the Dev Hub alias my-dev-hub. Your command looks like below.

sf org create snapshot --name dhsnapshot --source-org dreamhouse-org
--target-dev-hub my-dev-hub --description 'Snapshot of dreamhouse-org'

Note: This command kicks off an asynchronous process to create the snapshot and sets the status to InProgress. The status is changed from InProgress to Active once created. You can monitor the status of the snapshot creation using the sf org get snapshot command by providing the snapshot name or ID.

You can monitor the status of the above example using the following command.

sf org get snapshot --snapshot dhsnapshot --target-dev-hub my-dev-hub

You can also list scratch org snapshots that belong to the specified Dev Hub org using sf org list snapshot .

Step 4: Add scratch org name to the scratch org definition file

Create a scratch org definition file that references the snapshot. An example definition file for a dreamhouse scratch org with a snapshot name dhsnapshot would look like below.

{
"orgName": "Salesforce",
"snapshot": "dhsnapshot"
}

Note: We have used snapshot option instead of edition in the scratch org definition file. Also, you can’t specify features, sourceOrg, and releaseVersion in your snapshot scratch org definition file, but you can optionally add settings to override the default snapshot settings in the scratch org definition file.

Step 5: Create scratch org

Create the scratch org based on your snapshot using the sf org create scratch command. For example, if the scratch org definition file name is dhsnapshot-scratch-def.json, your command to create a scratch org with alias, dh-scratch-ci would look like below.

sf org create scratch --definition-file config/dhsnapshot-scratch-def.json
--alias dh-scratch-ci --wait 10 --target-dev-hub my-dev-hub

Check our video to see how you can create and use Scratch Org Snapshots.

Key considerations

• Unlike an org shape, a snapshot is captured from a scratch org and it includes installed packages, metadata, and data.
• A snapshot must belong to the Dev Hub org that you’re using to create the scratch orgs.
• Snapshots are static as they are captured at a point in time. Therefore, to update a snapshot, delete it and capture another snapshot.
• The time to create a snapshot depends on the size of the source scratch org. To speed up snapshot creation time, include only what’s necessary for your project.
• You can create a snapshot only from a scratch org, and conversely, you can create only scratch orgs from a snapshot.
• You can create up to five snapshots daily per Dev Hub org, with a maximum of five active snapshots.
• Snapshots expire after 90 days. When a snapshot expires, its status is updated automatically and its license becomes immediately available. You can automate snapshot creation using the CLI with a shell script (for Mac and Linux) or a PowerShell script (for Windows) to ensure that the snapshot is generated before it expires and remains available.
• You must use Salesforce CLI commands to create and manage your scratch org snapshots.
  • org create snapshot – Create a snapshot of a scratch org
  • org delete snapshot – Delete a scratch org snapshot.
  • org get snapshot – Get details about a scratch org snapshot
  • org list snapshot – List scratch org snapshots that belong to the specified Dev Hub org
• You can’t use a namespaced scratch org to create a snapshot. Snapshots are intended to include only dependent packages, metadata, and test data.

Scratch Org Snapshots capture the complete state of a scratch org, including data and metadata. They are ideal for quickly creating scratch orgs with predefined states for development or testing purposes, including data setup.

Scratch Org Shapes vs. Scratch Org Snapshots

Conclusion

Scratch Org Shapes and Snapshots are powerful features to enhance your Salesforce Developer experience. Org shapes replicate configurations for consistent environments used across teams, while snapshots allow rapid setup with predefined data and metadata. Start using these features today to empower your team with efficient and flexible development environments.

Resources

• Salesforce DX Developer Guide: Create a Scratch Org Based on an Org Shape
• Salesforce DX Developer Guide: Scratch Org Snapshots
• Salesforce CLI Setup Guide
• Video: Create a Scratch Org Based on an Org Shape
• Video: Create a Scratch Org Using Snapshots

About the author

Satya Sekhar Chegondi is a Lead Developer Advocate at Salesforce focusing on AI, Data, Lightning Web Components, and developer tools. He is passionate about sharing his knowledge about all that’s possible with the Salesforce Platform with various audiences in an understandable format. You can follow him on X and LinkedIn.