Click or drag to resize
Configuration Deployment

[This is preliminary documentation and is subject to change.]

It is common practice to build/develop a configuration in one environment (a development environment), and afterwards deploy it to some other environments (test, production). This is naturally repeated when releasing new versions of configurations.

Deployment of configurations is essentially a question of copying files from source configuration folder to the destination configuration folder. But there are a few things to consider...

This topic contains the following sections.

Important: some files should be deleted before deploying!

  • Files that exist in the source configuration, but not in the destination configuration, are created - no problem.

  • Files that exist in both the source configuration and the destination configuration, are overwritten - no problem.

  • Files that exist in the destination configuration, but not in the source configuration, will be left untouched. In some places this is not a problem - for example are forms included in the structure file by name, so if any old form definitions exist in the forms folder after deployment, they are not used. But such obsolete forms might a confuse a configurator using the editor to edit forms.

    But in other places it DOES matter. Examples:

    • The most important example is the SQL/Run folder. It is a convention, that all files in this folder should be run (as a batch) after deployment. The SQL scripts in this folder should create/update necessary database objects (tables, views, stored procedures, etc.). If an old script is left in this folder after deployment, it gets executed when the configurator runs all script in the folder - and that may cause a problem.

    • All files in the Views folder are presented for the user as clickable reports. If an old report is left in this folder after deployment, a user may click it and thus run a report that might not work - or a report that the user was not supposed to be able to run for security reasons.

    Therefore, the contents of the relevant folders should be deleted before deployment. It may be done in two ways:

    • Delete (the contents of) these specific folders:

      • Config/Library

      • JavaScript

      • SQL

      • Views

    • Recommended: Delete all files/folders in the configuration folder EXCEPT:

      • Server.config file

      • Config/Current folder

      • Log folder

Exceptions: folders / files with these names should NOT be deployed:
Caution note Caution

These folders / files contain environment specific configurations or data generated by the TOPICA framework. Therefore, they should NOT be copied from source configuration to destination configuration!

  • Folders:

    • Temp

    • Log

  • Files:

    • Server.config

    • .checkedoutstatus

Using the built-in user interface to deploy configuration

The deployment functionality built into the TOPICA framework allows the deployer to copy configuration files from one environment to another.

Caution note Caution

The deployment tool currently DOES NOT delete any files in the destination environment. It is possible to use the "TOPICA Explorer" tool to delete selected files / folders in the destination environment - but there is currently no way to "clean" the entire destination configuration with a single command.

Options:

  • Deploy the entire set of set of configuration files (initiated from main menu).

  • Deploy one folder (including subfolders) at a time (initiated from "TOPICA Explorer").

  • Deploy individual files one at a time (useful for "hotfixes" - initiated from "TOPICA Explorer").

This functionality automatically skips the folders / files in the exception list described above.

The deployment mechanism is implemented by a SOAP web service call, so the only requirement is HTTP access from source to destination. This makes it very easy to deploy from one environment to another - it is not necessary to move files manually to the target server, and it is not necessary to access the file system on the server running the destination environment.

Important note Important

When the TOPICA framework at the destination receives files to be deployed, they should obviously be written to the destination configuration folder. This requires that the "application pool user" has write access to the configuration folder.

"Manual" deployment of configuration

  • Make the source configuration files accessible from the destination server. If source and destination are on different servers, and there is no way to access the files system of both servers simultaneously by network shares (which is typically the case in production environments), this will require moving the files using FTP or similar tools.

    It is recommended to pack the source configuration files into one .zip-file. Make sure the files / folders on the exception list above are NOT included in the .zip-file (this will prevent accidental overwrite of these files).

  • Access the file system of the server running the destination environment. If you do not have network share access (as is typical for production environments, use "Remote Desktop Connection" or similar tool.

  • Launch "Windows Explorer" on the destination server.

  • Navigate to the destination configuration folder.

  • Caution note Caution

    Delete the files / folders that should be deleted before deploying (see above).

  • Copy all folders / files (with above listed exceptions) from the source configuration folder to the destination configuration folder.

After deployment of configuration

  • Log in to the destination application.

  • If any forms and/or the structure file were updated: Update Data Dictionary.

  • If Data Dictionary was updated, or there were changes to any SQL-files defining database objects: Run all SQL scripts in folder SQL/Run (using the "batch" command).

  • Test!