How to: Create Environment Specific Settings in Content Hub

Sometimes in Content Hub, we need to store some values that are specific to a particular environment - The ideal place for these is an environment specific setting. Environment specific settings aren't particularly well known - probably because they can't be created via the UI, but they are super useful, and are exactly what we need here. When exporting settings from the Content Hub environment, settings marked as being environment specific are excluded from the package, meaning you can safely deploy between environments without fear that these values will be overwritten.

Create a Setting Entity

As environment specific settings cannot be created using the UI, we can instead use the API. To do this create a HTTP POST request to /api/entities with the following body:

{
    "identifier": "",
    "entitydefinition": {
        "href": "{{host}}/api/entitydefinitions/M.Setting"
    },
    "relations": {
        "SettingCategoryToSettings": {
            "parent": {
                "href": "{{host}}/api/entities/{{SettingCategoryId}}"
            }
        }
    },
    "properties": {
        "M.Setting.Name": "{{SettingName}}",
        "M.Setting.Label": {
            "en-US": "{{SettingLabel}}"
        },
        "M.Setting.Value": {},
        "M.Setting.EnvironmentSpecific": true
    }
}

Line 19 is the crucial one here - setting the M.Setting.EnvironmentSpecific property to true. This, as mentioned earlier, is not exposed through the UI and can only be set on creation (I.E. it cannot be updated later). Once created though, the setting can be managed in the same way as any others in the Manage > Settings section.

You will of course need to replace the tokens with your own specific values (particularly the identifier on line 2), and either choose an existing Setting Category or create a new one.

Create A Setting Category Entity

Creating a new Setting Category is very similar to creating a Setting. Simply create a HTTP POST request to /api/entities, this time with the following body:

{
    "entitydefinition": {
        "href": "{{host}}/api/entitydefinitions/M.SettingCategory"
    },
    "properties": {
        "M.SettingCategory.Name": "{{SettingCategoryName}}",
        "M.SettingCategory.Label": {
            "en-US": "{{SettingCategoryLabel}}"
        }
    }
}

Again, you will need to replace the tokens with your own desired values. The API will respond with a JSON payload containing the id and identifier of your newly created Setting Category which you can use to create a Setting. Easy right? 😊

No go forth and populate the (Content Hub) world with environment specific settings!