Some configurations / applications need a lot of interfaces to external systems and/or a lot of configuration options in order to customize the application for different customers.

In these situations, you may end up with a lot of parameters in Server.config.

The problems with this is:

• It might be difficult to get an overview of which parameters should have what value for the individual customers. There is no direct way to tell what parameters should be set for each individual customer.

• Parameters for interfaces typically differ from type of environment - settings for URLs, credentials, etc. will differ from development to production environments.

• Server.config should NOT be kept under source control. As a consequence, there is no version control, and no (automatic) backup copies - the value of the parameters used for production environments exist ONLY in the Server.config files on the production servers - there is no easy way to "reconstruct" a production environment from the code base checked into the source control system.

The solution is a feature, that makes it possible to create a "library" of (smaller) .config files, that may be combined.

• The .config files in the "library" are not "active", e.g. they are not read in, and the parameters in these files therefore do not have any effect (per default).

• Each file in the "library" may be activated / deactivated from the web user interface (copied to a different folder) - i.e. it is not necessary to access the file system of the web server and edit files, as is the case when all environment specific parameters are in Server.config.

• These "library" files should be stored in source control. (making sure that backup copies exist, and that environments may be easily reconstructed).

  Because "library" files are not "active", there is no risk of accidentally overwriting "active" parameters, when new version of the configuration is deployed.

In the configuration folder, create a new subfolder Config, inside this create a subfolder Library.

In Config/Library, create any number of .config files (file names may be freely chosen - except that extension must be .config).

The resulting folder/file structure should look like something like this:

<configuration folder>
    Config
        Library
            Customer_X.config
            Customer_Y.config
            Customer_Z.config

In this example, an application is meant for 3 customers Customer_X, Customer_Y, and Customer_Z.

"Activating" a file from the library is done by copying the file to the folder Config/Current (the web user interface to copy the library files will create this folder, if it does not exist already). So after "activating" the Customer_X.config file, the structure will be:

<configuration folder>
    Config
        Library
            Customer_X.config
            Customer_Y.config
            Customer_Z.config
        Current
            Customer_X.config

Deactivating a file is simply a matter of deleting it from the Config/Current folder.

The files in the library must have same format as the Application.config and Server.config files. The keys may be those "known" by TOPICA (i.e. keys that exist in the framework's Web.config file), or may be configuration / application specific (i.e. keys that exist in the Application.config file).

Extending on the example from above, assume that an application has interfaces named A and B.

• Each interface needs a set of parameters (URLs for web service calls, credentials, etc.).

• Parameters like URLs for web service calls, credentials, etc. DIFFER between environments (i.e. values in production environments differ from values in development environments).

• The set of activated interfaces depend on customer.

The library might look like this:

<configuration folder>
    Config
        Library
            Customer_X.config
            Customer_Y.config
            Customer_Z.config
            InterfaceA_DEV.config
            InterfaceA_PROD.config
            InterfaceB_DEV.config
            InterfaceB_PROD.config

Customer_X uses both InterfaceA and InterfaceB, Customer_Y uses only InterfaceA, and Customer_Z does not use any of the interfaces.

Because Customer_X is the customer with the most interfaces, configure the development environment like this:

<configuration folder>
    Config
        Current
            Customer_X.config
            InterfaceA_DEV.config
            InterfaceB_DEV.config

Production environment for Customer_X:

<configuration folder>
    Config
        Current
            Customer_X.config
            InterfaceA_PROD.config
            InterfaceB_PROD.config

Production environment for Customer_Y:

<configuration folder>
    Config
        Current
            Customer_Y.config
            InterfaceA_PROD.config

Production environment for Customer_Z:

<configuration folder>
    Config
        Current
            Customer_Z.config

Note

A few simple rules apply: In each environment one and only one customer should be activated. Each interface should be activated for development, production - or not at all. The file naming convention in above examples is chosen to make it easy to check above mentioned rules: The part of the file names before "_" should be UNIQUE in each environment. The system does not check this - it is up to the deployer to check this!

The TOPICA framework comes with a "library" of its own. Naturally, files in this library only contain parameters with keys, that are "known" by the TOPICA framework (i.e. keys that exist in the framework's Web.config file).

The framework library consists of this folder:

<framework folder>
    ConfigLibrary
        !Debug.config
        !LockForDeployment.config

Files in this folder may be copied to <configuration folder>/Config/Current like the files from the configuration's library.

Filenames in the framework's library start with "!" for two reasons:

• To minimize "name clash".

• To control sorting - files with names starting with "!" will appear first.

To ensure backward compatibility, the load sequence (= the sequence in which the TOPICA framework reads the files) is as follows:

1. Web.config

2. Application.config

3. all the activated "library" files, i.e. the .config-files in Config/Current.

4. Server.config

If a given parameter (identified by a key value) is defined in several of the files read, the value from the file that is read LAST will "win".

That is: if a parameter is defined both in an activated library .config-file and in Server.config, that value from Server.config is used (because it is read last).

So to make use of the "library" described here, parameters defined in "library" files should NOT be defined in Server.config!

Important
When starting to use the ConfigLibray functionality described here, it will probably be because of the problems mentioned at the beginning. So you will probably need to REMOVE most of the contents of the .config files in ALL environments (after having put the definitions in relevant "library" files).

As mentioned earlier, the TOPICA framework contains a simple user interface, that makes it possible to activate / deactivate individual "library" .config files.

• In the main menu select Tools / Framework Tools.

• Click ConfigLibrary.aspx.

• The displayed page shows 3 lists of files:

  • The library defined in the TOPICA framework.

  • The library defined in the current configuration.

  • The list of activated library files.

• To activate a file, click on the "Copy" button next to the file in one of the library lists.

• To deactivate a file, click on the "Delete" button next to the file in list of activated files.

• To view the contents of a library file, click the hyperlink showing the file name.

Security Note
As with all other functions, where the TOPICA framework writes files to the configuration folder, it is a requirement, that the Windows user that it set to "run" the web home (that is: the "application pool user") has write access to the folder in question.