Build Your Own Scratch Org Definition File

Scratch Org Definition File Name

You indicate the path to the scratch org configuration file when you create a scratch org with the force:org:create CLI command.

• If you’re using Salesforce CLI on the command line, you can name this file whatever you like and locate it anywhere the CLI can access.
• If you’re using Salesforce Extensions for VS Code, make sure that the scratch org definition file is located in the config folder and its name ends in scratch-def.json.

If you’re using a sample repo or creating a Salesforce DX project, the sample scratch org definition files are located in the config directory. You can create different configuration files for different org shapes or testing scenarios. For easy identification, name the file something descriptive, such as devEdition-scratch-def.json or packaging-org-scratch-def.json.

Scratch Org Definition File Options

Here are the options you can specify in the scratch org definition file:

Sample Scratch Org Definition File

1{
2  "orgName": "Acme",
3  "edition": "Enterprise",
4  "features": ["Communities", "ServiceCloud", "Chatbot"],
5  "settings": {
6      "communitiesSettings": {
7          "enableNetworksEnabled": true
8      },
9      "mobileSettings": {
10          "enableS1EncryptedStoragePref2": true
11      },
12      "omniChannelSettings": {
13          "enableOmniChannel": true
14      },
15      "caseSettings": {
16          "systemUserEmail": "support@acme.com"
17      }
18  }
19}

Some features, such as Communities, can require a combination of a feature and a setting to work correctly for scratch orgs. This code snippet sets both the feature and associated setting.

1"features": ["Communities"],
2    "settings": {
3        "communitiesSettings": {
4          "enableNetworksEnabled": true
5      },
6        ...

Create a Custom Field for ScratchOrgInfo

You can add more options to the scratch org definition to manage your Dev Ops process. To do so, create a custom field on the ScratchOrgInfo object. (ScratchOrgInfo tracks scratch org creation and deletion.)

1. In the Dev Hub org, create the custom field.
   1. From Setup, enter Object Manager in the Quick Find box, then select Object Manager.
   2. Click Scratch Org Info.
   3. In Fields & Relationships, click New.
   4. Define the custom field, then click Save.
2. After you create the custom field, you can pass it a value in the scratch org definition file by referencing it with its API name.

   Let’s say you create two custom fields called workitem and release. Add the custom fields and associated values to the scratch org definition:

   1{
   2     "orgName": "MyCompany",
   3     "edition": "Developer",
   4     "workitem__c": "W-12345678",
   5     "release__c": "June 2018 pilot",
   6     
   7     "settings": {
   8         "omniChannelSettings": {
   9              "enableOmniChannel": true
   10     }
   11           }
   12}

3. Create the scratch org.

Set Object-Level Sharing Settings and Default Record Types

To install successfully, some packages require that you define object-level sharing settings and default record types before installation. Set the sharing settings and default record types with objectSettings. In this sample scratch org definition file, we set a sharing model and a default record type for opportunity, and a default record type for account.

1{
2  "orgName": "MyCompany",
3  "edition": "Developer",
4  "features": ["Communities", "ServiceCloud", "Chatbot"],
5  "settings": {
6      "communitiesSettings": {
7          "enableNetworksEnabled": true
8      }
9  }
10  "objectSettings": {
11     "opportunity": {
12        "sharingModel": "private",
13        "defaultRecordType": "default"
14     },
15     "account": {
16        "defaultRecordType": "default"
17     }
18  }
19}