Table of Content

How to Create a Scratch Org from a Shape Org in Salesforce


Salesforce developers have long been using scratch orgs as playgrounds for testing out code. Be it when they’re starting a new project or checking whether a to-be-deployed feature works properly, everything must be first examined before it goes live.

All is fine and dandy, but developers have been facing one major letdown with Salesforce scratch orgs. The configuration process when creating such an org can get very time-consuming and tedious if something changes on the production org. Many developers are now turning to Salesforce Developer Org for initial development and testing before using scratch orgs. Additionally, they often create a Developer Org Salesforce environment to facilitate a smoother transition and configuration process. But luckily the 2021 Salesforce winter release has brought some really good news. Shape orgs!In this article, we’ll briefly introduce you to scratch orgs in Salesforce. Plus, we’ll provide you with a simple and easy-to-follow guide (with examples) on how to create a scratch org on the basis of a Salesforce shape org.

What Is a Scratch Org?

In simple terms, a scratch org is a disposable environment in that developers can use to test their code and different features prior to their implementation. Scratch orgs are customizable and capable of imitating various editions of a Salesforce platform.

Among the things that make scratch orgs so great, they:

  • are able to boost the productivity of developers,
  • make it simpler to hold automated tests, 
  • enhance the development and integration process in general.

Why Is Creating a Scratch Org Trickier than It Seems?

You can create a scratch org in more than one way. And, interestingly, there is a perception that it all takes just a couple of seconds. The latter is only partially true because, initially, when you create a new scratch org, it’ll be blank. This means that it won’t have a huge portion of the data that your source org does and that you’ll need for testing. Such data is, for instance, your custom objects, , reports, apex triggers, among other things.

This is why a big deal of preparation is required as you build the scratch org. In essence, you need to deal with many configurations so that the scratch org will have identical settings, features, and licenses (a.k.a. the org's shape) and define them all in a scratch org configuration file. It should also reflect the original org you're using as a source. As you might have already guessed, configuring a scratch org as you create it is quite a dreary process. Copying all the setups implies lots of time, effort, and attention to detail. Not to mention the continuous necessity to monitor that everything is up-to-date.

And the worst part is that when code is developed and transferred between orgs, this often leads to conflicts in files and metadata which is, obviously, bad.

Is There a Workaround Solution?

Fortunately, the 2021 Salesforce winter release brought amazing news. A solution that can make the lives of developers much easier as now they can quickly create shape orgs without all the painstaking work with configurations. Let’s give a warm welcome to the shape org solution!The shape org has currently been added in its beta version, you can read more about it . But thankfully this beta feature already works well and it’s convenient too! It allows you to create a scratch org based on a production org. This concerns large-scale settings such as the enabled features (not the code, triggers, etc.). Want to know how?

Creating a Scratch Org via an Org Shape in Salesforce: Step by Step

In this part of the post, we'll walk you through the scratch org creation process using the Salesforce org shape for your production org.

Step 1: Getting Started

Go to the Setup section and type in “Org Shape” in the Quick Find box. Then select “Org Shape”. In the source org, click on the switch “Enable Org Shape for Scratch Orgs (Beta)” located on the right.

Important note: you must repeat this step both on your production org and on your dev org even if you’re creating a shape org just for the production one. This is one of the limitations of the beta version.

Scratch Org in Salesforce

Step 2: Copy the SF Organization ID

Go to the dev org. In the Setup section, enter “Company Information” in the Quick Find box and then select “Company Information”. Copy the Organization ID.

Organization ID in a Scratch Org in Salesforce

Step 3: Paste the Organization ID

Now paste this Organization ID in the production org and press “Save”. It should look like this:

Pasting the Organization ID in the Salesforce Scratch Org

Step 4: Authorize both orgs in VSC

Go to the VSC and authorize both orgs using sfdx. If they’re already authorized on your end, then you can skip this step. If not, do the following:

  • For the prod org:
sfdx auth:web:login --setalias my-prod
  • For the dev org:
sfdx auth:web:login --setalias my-dev

Step 5: Create the shape org using sfdx

Now create the shape org with the help of sfdx. To do this, run the following command, and indicate the name of the production org in place of <alias>:

sfdx force:org:shape:create -u <alias>

Keep in mind that the command is executed asynchronously. To monitor the status you can use:sfdx force:org:shape:list

Step 6: Create a scratch org

So, the Salesforce dx org shape is created and has the "Active" status. Now, you need to set up a Salesforce Scratch Org Definition File. This file defines the configuration of your scratch org and ensures it matches your specific development needs. Here's how to prepare it: Create a new file in your VSC project. Name it project-scratch-def.json under the config directory. Specify the features, settings, and edition of your scratch org. For example, "features": ["API", "CustomApps"], Save the file with the correct settings before proceeding. This definition file imitates the design of an org that you can employ for production, packaging, or sandbox scenarios during the development lifecycle. To develop a scratch org on the basis of the shape org, create a file for the VSC project using the config/shape-scratch-def.json path.

The file should contain the following:

	"orgName": "somename",
	"sourceOrg": "00D4T000*******"

In this case, the source Org will be the Organization ID from your production org.

CReating a Scratch Org in Salesforce

Important note: if you’d like, you can also add custom setups to your scratch org. You can read more about this .

If you're going to use several scratch orgs within the same project environment, don't forget to set one as a default scratch org. This way, you won't have to specify the target org in every command. You can utilize the same scratch org and easily switch between tasks or testing environments.

Step 7: Run the “create” command

Finally, run this command to finish up the process:

sfdx force:org:create -f config/shape-scratch-def.json --durationdays 30

Get a Free Salesforce Audit Example

Explore our Salesforce audit report on diagnosing common bottlenecks in the Salesforce ecosystem.

Over to You

Summing up everything covered in this article, scratch orgs make up a crucial part of the work of . They’re needed for testing new features and code which is clearly an important ongoing process. As shown in the step-by-step instructions on this page, it is now actually very easy to create a scratch org using the shape org. And even though the shape org solution that was introduced by Salesforce in winter 2021 is still in its beta version, it’s already an amazing and time-saving way to create a scratch org.

Related Articles

Getting Started With Governor Limits in Salesforce (Updated 2024)
Max Matin
Max Matin, Certified Community Cloud professional

Getting Started With Governor Limits in Salesforce (Updated 2024)

8 min
Jun 21, 2023
Validation Rules in Salesforce: A Simple Guide (Updated 2024)
Max Matin
Max Matin, Certified Community Cloud professional

Validation Rules in Salesforce: A Simple Guide (Updated 2024)

7 min
Jul 5, 2023
Salesforce Workflow Rules Explained
Alex Husar
Alex Husar, Onilab CTO

Salesforce Workflow Rules Explained

9 min
Mar 23, 2020

Let’s stay in touch

Subscribe to our newsletter to receive the latest news and updates.