Move to Salesforce DX more easily with Org Shape for Scratch Orgs

Scratch Definition File, great but…

If you made the move to Salesforce DX from an existing Salesforce org :

You may know that building the Scratch Definition File for your Scratch Org can be painful.

It’s a powerful tool. But then you need to be sure to activate the exact same features and settings that you have turned on in your Production Org.

So for instance

If you work with Communities, you would have to create a Scratch Definition File that looks like this :

{
  “orgName”: “Texeï”,
  “edition”: “Enterprise”,
  “features”: [“Communities”],
  “settings”: {
    “communitiesSettings”: {
      “enableNetworksEnabled”: true
    }
  }
}

Seems easy, right ?

Well it is, if you know that you need to combine the Communities feature to the enableNetworksEnabled setting. And when your Scratch Org is setup with Community enabled, you’ll then noticed that you don’t have any Community license !

And this is only for features and settings you know about. But you’re also likely to encounter issues because of features or settings that are activated in your Production Org and that you’ve never heard of. Just have a look to the number of existing Settings to get an idea.

You’ll find solutions and workarounds for almost all your problems but at the cost of hours of work.

As Scratch Org Settings are matching Metadata API Settings. We tried to build a command in our sfdx plugin to extract Scratch Definition files. Yet because of the lack of an API for features, and the link between them and the Settings, this is very far from being perfect.

And at the end of your Scratch Definition File journey, you’ll end up with one remaining issue: Settings or Features that don’t have an API.

This is painful because this will prevent you from pushing stuff to your Scratch Org. Or you may end up retrieving stuff that are part of the Scratch Org. But not part of your Production Org.

For instance

I never found how to disable Portal stuff on some Scratch Orgs, bringing fields like IsVisibleInSelfService to your repo.

Until now you could either omit these stuff from your repo, manually activate a feature, or script it with a tool like Puppeteer. That may break at any time !

Enters Org Shape

Starting Winter ’21, we are be able to use Org Shape in any DevHub.

To use it, just activate Org Shape under Setup and run the following command : sfdx force:org:shape:create -u MyDevHub

According to the doc you’re not supposed to add the Org Id in the text area below if your DevHub is the same as the Org where Org Shape is activated. However I had at least 1 Org where I had to do it anyway to make it work. Maybe this was just an issue at the beginning of the beta. 🤷🏻‍♂️ If you encounter any error be sure to look at Scratch Org creation error codes.

Then just add a sourceOrg tag with your DevHub Org Id :

{ 
  “orgName”: “Texeï”, 
  “sourceOrg”: “00D1L030R954P31”, 
  “settings”: { 
    “mobileSettings”: { 
      “enableS1EncryptedStoragePref2”: false 
    }
  } 
}

Notice 2 things from the Scratch Definition File below :

• You’ll have to remove some flags, like edition that is deduced from your shape.
• You definitely tweak a few features or settings to change some of them compared to your DevHub.

Example 1 :

Here I’ve switched enableS1EncryptedStoragePref2 to false, which is Lightning Experience’s cache. This is something you don’t want to deactivate in Production. But definitely want to have turned off in a development environment.

This is also a great opportunity to test new features. Without having to turn them on in your DevHub or contact Salesforce support.

Example 2 :

Testing Person Account impact in your org is just a matter of adding the PersonAccounts feature in your Scratch Definition File.

Another great thing with Org Shape is that all features and settings are copied over, even the ones that don’t have an API !

Example 3 :

You can’t activate “Allow Users to Relate Multiple Contacts to Tasks and Events” in “Activity Settings” because the related Metadata API flag is read only (see allowUsersToRelateMultipleContactsToTasksAndEvents here).

Well with Org Shape the setting is activated in your Scratch Org if it was in your Prod org ! (note that for this one we have built a sfdx texei:sharedactivities:enable command, but we can’t build a command for every missing API).

During the beta, you may encounter some issues, look at the limitations here. So far there is nothing more than a random “A fatal signup error occurred. Please try again” error from time to time, and you’ll just have to…try again.

Also, so far you’ll need to recreate a new shape for every Salesforce release.

Finally, be sure to have a look to the Org Shape for Scratch Orgs Chatter group in the Trailblazer Community.

This feature is definitely a great tool that will save you time to setup a new DX project. Have fun with Scratch Orgs and Org Shape !