Documentation Center

Multi-leveled connector configuration

Connectors require that you provide custom configuration for the connector's Add-ons package in the form of a JSON configuration file.

Multi-level file structure

Tridion Integration Framework supports a multi-leveled approach to connector configuration. Within the JSON configuration file, you can configure each connector per namespace and per environment, as well as generally for the connector overall. Namespace configuration enables you to include multiple configurations per connector package.

The following diagram illustrates in the simplest form the multi-level structure of the configuration file:

This illustration shows how the file structure represents a connector's integration with both the Content Management and Content Delivery sides of SDL Tridion Sites, as well as with multiple Content Delivery environments.

At each level, you can include a configuration object with settings (key-value pairs) that configure that particular level. You can optionally include a namespaces object with one or more namespaces that you want to expose. If the same configurations occur at deeper levels, then override the equivalent setting at a higher level. In addition, a value defined in the configuration file will also override any default values that might exist for the same setting in the manifest.

General, all-environment configuration

The top-level configuration object contains general settings for the connector that will apply to all environments. For example, the following code block illustrates the general connector configuration excluding any environment-level configuration:

{
	"configuration": {
		"CONNECTOR_NAME": {
 		"configuration": {
  				// Connector-level settings for all environments and namespaces
			},
			"namespaces": {
				"NAMESPACE_ID": {
	  			// Connector-wide, namespace-specific settings for all environments 
				},
				"NAMESPACE_ID": {
					 // Connector-wide, namespace-specific settings for all environments
				}
			}
		}
	},
}

CONNECTOR_NAME is the is the name of the connector, as defined by the name setting in the manifest file (same as you used for the file name). Within this object, add configuration settings that apply to all environments as well as all namespaces.

NAMESPACE_ID identifies one or more namespaces. Namespace IDs should be unique across connectors. Within this object, define configuration settings that apply to all environments, but which is specific to this namespace.

Environment-specific configuration

Add configuration that is specific to Content Management and Content Delivery environments with the appropriate sections (objects) as follows:

  • To enable for the Content Management environment, include the sitesCm section. Within this section, you need to configure the stub Folders or stub Categories that this connector will make use of in Content Manager.
  • To enable for a Content Delivery environment, include a section for the environment name defined in the cdenvironment variable. The defaults are staging and live.
You need a separate section for each environment and in each section, the isEnabled property individually enables an environment for the connector. Set the value as follows:
  • True enables the environment with respect to the connector
  • False disables the environment with respect to the connector

Tridion Integration Framework checks the isEnabled setting when it receives a request from an Application Client (such as External Content Library or Public Content API) for all the connectors for the environment.

Note the following:
  • If no environments are specifically enabled, the Content Management environment will be enabled automatically.
  • If any Content Delivery environment is enabled, you must also enable the Content Management environment in order for it to be available to the connector.
  • For Content Delivery, you always need to explicitly enable each environment.

The following illustrates the general structure for the Content Management and a staging environment:

"sitesCm": {
    "isEnabled": true,
    "CONNECTOR_NAME": {
      // General environment-level settings, which apply to all namespaces
      "namespaces": {
        "NAMESPACE_ID": {
          // Environment-wide, namespace-specific settings, like these:
          "displayName": "Connector ABC",
          "stubFolders": [ "tcm:2-71-2" ],
          "privilegedUserName": "Administrator"

        }
      }
    }
  },
  "staging": {
    "isEnabled": true,
    "CONNECTOR_NAME": { 
    	"namespaces": {
         "NAMESPACE_ID": {
         }
    }
  }

Example file

The following sample code illustrates the configuration file of a new .NET connector for YouTube, which has two defined namespaces and integration on the Content Management-side:

{
	"configuration": {
		"YouTube": {
 		"configuration": {
  				"apiKey": "API_KEY_123456",
  				"channels": ["CHANNEL_A_123456",
  				"CHANNEL_B_123456",
	  			"CHANNEL_C_123456"],
	  			"updatableChannels": ["CHANNEL_B_123456"],
	  			"pageSize": 20,
	  			"enableTemplateCapability": "true"
			},
			"namespaces": {
				"ytb": {
	  				"displayName": "YouTube",
  					"stubFolders": ["tcm:1-4-2"],
				},
				"ytb1": {
					  "displayName": "YouTubeDynamic",
				  	"stubFolders": ["tcm:1-4-2"],
				}
			}
		}
	},
	
	"sitesCm":
	{
		"isEnabled": true,
		"configuration": {
		  		"apiKey": "API_KEY_123456",
		  		"channels": ["CHANNEL_A_123456",
	  			"CHANNEL_B_123456",
  				"CHANNEL_A_123456"],
  				"updatableChannels": ["CHANNEL_B_123456"],
	  			"pageSize": 2,
	  			"enableTemplateCapability": "true"
			}
			
	}
}