Configuring a Connector

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

Before you begin

To complete a configuration file for an Connector, you need to know the following:

  • The name of the Connector as it is defined in the Add-on's manifest file.
  • The name of each Content Delivery environment to be specifically configured for an Connector, as they are defined in the cdenvironment environment variable of each environment.

About this task

After adding a Connector to your SDL Tridion Sites implementation, create a JSON configuration file to your needs and upload it to the Add-ons service. The configuration includes settings that are specific to your implementation, such as endpoint URL, username, password, and more.

Procedure

  1. In a plain text editor, create a new file.
  2. Add a top-level configuration object that contains general settings for the Connector that will apply to all environments. You can optionally include a namespaces object with one or more namespaces that you want to expose.

    For example, the following code block illustrates the general Connector configuration with no environment-level configuration:

    
    {
        "configuration": {
            "CONNECTOR_NAME": {
    
                // General connector-level settings, which apply to all environments and namespaces   
                      
                "namespaces": {
                    "NAMESPACE_ID": {
    
                         // Connector-wide, but namespace-specific settings that apply to all environments                     
    
                    },
    
                         // Other namespaces...
                },
            }
        },
    
    }
    

    Where:

    • CONNECTOR_NAME is the is the name of the Connector, as defined by the name setting in the manifest file (same as you just 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.
  3. (Optional) To add configuration that is specific to an environment, add a ENVIRONMENT section, using the following general structure:
    
        "ENVIRONMENT": {
            "isEnabled": "ENABLE", 
            "CONNECTOR_NAME": {
    
                // General environment-level settings, which apply to all namespaces
    
                "namespaces": {
                    "NAMESPACE_ID": {
    
                         // Environment-wide, but namespace-specific settings                     
                    },
    
                    // Other namespaces...
                }           
            },
    
            // Environment-level configuration for other extensions available in the same package...
    
         },
    
         // Configuration for additional environments...
    

    Where:

    • ENVIRONMENT is one of the following:
      • For the Content Management environment, it is always equal to sitesCm (case sensitive).
      • For the Content Delivery environment, it is equal to the value defined for the cdenvironment variable. The defaults are staging and live.
    • ENABLE is either True or False to individually enable an environment with respect to the Connector. Tridion Integration Framework checks this 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.
      • True enables the environment with respect to the Connector
      • False disables the environment with respect to the Connector
    • CONNECTOR_NAME is again the is the name of the Connector, and is the same throughout this file wherever this key is specified. Within this object, include Connector settings that apply generally to the environment, including all namespaces.
    • NAMESPACE_ID identifies an exposed namespace. Within this object, include Connector configuration settings that apply only to this specific namespace (within the environment).
  4. Repeat the previous step to configure the Connector for use in additional environments.
  5. Optionally, in the same configuration file, you can define additional extensions should be available with the Connector. Follow the same pattern as used for the Connector object.
  6. 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.

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

Example configuration created from the .NET template

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"
			}
			
	}
}