Documentation Center

Creating an Add-on configuration file

Define custom configuration for an Add-on in a JSON file and upload it using the Add-ons feature.

Before you begin

To complete a configuration file for an Add-on, you need to know the following:

  • The name of each Extension in the Add-on that you will be giving specific configuration. These are defined in the Add-on's manifest file.
  • The name of each Content Delivery environment to be specifically configured for an Extension, as they are defined in the cdenvironment environment variable of each environment.

Procedure

  1. In a plain text editor, create a new file.
  2. Add the following sample JSON code to define the general structure:
    {
        "configuration": {
            "EXTENSION_NAME": {
    
            }
        },
        "sitesCm": {
            "isEnabled": true,
            "EXTENSION_NAME": {
    
            }
        },
        "CDENVIRONMENT": {
            "isEnabled": true,
            "configuration": {
              "SYSPROPNAME1": "SYSPROPVALUE1",
              "SYSPROPNAME2": "SYSPROPVALUE2"
            },
            "EXTENSION_NAME": {
    
            }
        }
    }

    Where:

    • EXTENSION_NAME is the name of the extension as it is defined by the name field in the Add-on's manifest file
    • sitesCm identifies the Content Management environment. it is always equal to "sitesCm" (case sensitive)
    • CDENVIRONMENT is equal to the value of a cdenvironment environment variable, as set in one Content Delivery environment. By default, there are two defined environments, "live" and "staging". You can use this feature to define different configurations for different types of Content Delivery environment.
    • SYSPROPNAME1, SYSPROPNAME2 and so on are names of environment variables you want to set for this Add-on in the Content Delivery environment identified by CDENVIRONMENT
    • SYSPROPVALUE1, SYSPROPVALUE2 and so on are values you want to set for those environment variables for this Add-on in the Content Delivery environment identified by CDENVIRONMENT

    The sample shows one extension; however, if the Add-on includes multiple extensions, you can individual configure each extension within each of the sections. Use the following example shows three extensions in the configuration section:

    "configuration": {
      "Extension1": {
        // configuration for extension1
      },
      "Extension2": {
        // configuration for extension2
      },
      "Extension3": {
        // configuration for extension3
      }
    },

    Use this same pattern in each of the sections to apply extension-specific configuration. The next steps describe each of the sections in more detail.

  3. In the top-level configuration section, define configuration for each extension in the Add-on that should apply to all environments. If you have no such configuration, you can leave out this top-level configuration section.
  4. In each of the environment sections (sitesCm or a CDENVIRONMENT section), add configuration that is specific to that environment.
    • isEnabled is set to either true or false to enable or disable this extension in that specific environment, respectively.
    • EXTENSION_NAME is the name of the extension, and is the same throughout this file wherever this key is specified. Within this section, include settings that apply generally to this extension.
    • If you define an environment-wide configuration section for CDENVIRONMENT, you do not need to also specify an EXTENSION_NAME section.

    If your Add-on package requires no configuration at all for a specific environment, you can remove that environment section. On the one hand, an Add-on may contain no Extension at all for a specific environment (say, if it contains only Content Delivery extensions, you don't need the sitesCm section). On the other hand, the Add-on may contain an Extension for a specific environment, but there's nothing to configure.

  5. Save the file in the JSON format.

    The file name can be whatever you like; however, as best practice, we recommend that you use ADDONFEATURENAME_CONFIG where ADDONFEATURENAME corresponds to the name setting in the manifest file. For example, ADDONFEATURENAME_CONFIG.json.

  6. Upload the configuration file from the screen showing Add-on details. If the Add-on already has a configuration file, your new file replaces the existing one.

Example configurations

The following sample code illustrates the configuration file for a very simple Add-on with a single extension named TCMExtension, which modifies a schema name from a value set in "titlebefore" to the value set in "titleafter":
{
     "configuration": {
          "TCMExtension": {
          "titlebefore": "OnSaveTitleChangeExtension_Schema1",
          "titleafter": "OnSaveTitleChangeExtension_Schema2"
          }
     }
}
The following sample shows a configuration for a staging Content Delivery environment only:
{
  "staging": {
    "isEnabled": "true",
    "configuration": {
      "indexconnectiontimeout": 10000,
      "indexreadtimeout": 30000,
      "indexwritetimeout": 30000,
      "indexmaxidleconnections": 30,
      "discoveryurl": "DISCOVERY_URL",
      "clientid" : "cduser",
      "clientsecret": "PASSWORD"
    }
  }
}