Get More Configuration Options with Scratch Org Settings

Have you ever wished that you could spin up a scratch org with a specific org setting only to find out that it wasn’t supported? With scratch org settings, you can configure your scratch orgs with any Metadata API setting.

Where: This change applies to Lightning Experience, Salesforce Classic, and all versions of the Salesforce app in Developer, Enterprise, Group, and Professional editions.

Who: You can create scratch orgs if you turned on Dev Hub in your production org, enabled Dev Hub in a Developer Edition org, or have a trial Dev Hub org.

Why: Scratch org settings are a new format for defining org preferences in the scratch org definition. Because you can use all Metadata API settings, this format is the most comprehensive way to configure a scratch org. If a setting is supported in Metadata API, it’s supported in scratch orgs. Settings provide you with fine-grained control: You can define values for all fields for a setting, rather than just enabling or disabling it.
Important

Important

In Winter ’19, you can specify scratch org settings or org preferences in your scratch org definition file, but not both. We encourage you to convert org preferences to scratch org settings in your scratch org definition. Scratch org settings provide more settings that aren’t currently available as org preferences. We plan to deprecate support for org preferences in Spring ’19.

How: Replace orgPreferences with org settings in the scratch org definition file.

This scratch org definition is configured using org preferences:

{
    "orgName": "Acme",
    "edition": "Enterprise",
    "features": ["Communities", "ServiceCloud", "Chatbot"],
    "orgPreferences" : {
        "enabled": ["NetworksEnabled", "S1DesktopEnabled", "S1EncryptedStoragePref2"]
     }
}

Here’s how the same scratch org definition looks after converting to scratch org settings:

Important

Important

Although the settings are upper camel case in the Metadata API Developer Guide, be sure to indicate them as lower camel case in the scratch org definition.

{
  "orgName": "Acme",
  "edition": "Enterprise",
  "features": ["Communities", "ServiceCloud", "Chatbot"],
  "settings": {
      "orgPreferenceSettings": {
          "networksEnabled": true,
          "s1DesktopEnabled": true,
          "s1EncryptedStoragePref2": false
      },
      "omniChannelSettings": {
          "enableOmniChannel": true
      },
      "caseSettings": {
          "systemUserEmail": "support@acme.com"
      }
  }
}

With org preferences, you can only enable or disable the preferences. And you have access to only those settings that were designed to work with scratch orgs. With scratch org settings, you have access to all Metadata API settings, such as omniChannelSettings and caseSettings, that weren’t available as org preferences. And what’s really powerful is that you can now configure non-Boolean fields. For information on Metadata API settings and their supported fields, see Settings in Metadata API Developer Guide.