Overview of the Tool

CTT (Configuration Transport Tool) is a tool for Efecte Service Management (ESM) administrators to visualize changes made to the configuration of the application.

CTT provides a way to transport the changes between environments. In CTT, it is possible to select changes and create a configuration file, which can then be imported to ESM to automatically make changes to that configuration.

CTT compares and shows the differences between two configuration files. Typically one file is from test environment and another from production environment. 

Requirements and Availability

Usage of the tool requires the ability to export configurations from both the source and target ESM environments, through Maintenance → System settings → Export configurations.

Configuration transport between environments (import of configuration file created with CTT) is supported starting from ESM version 2023.3. Not all items are supported, see below for more information.

Currently CTT is offered through one shared instance available from Efecte Cloud. You can access CTT  environment here: CTT environment

Use Case

The administrator can view what changes have been implemented in the test environment that have not yet been moved into production. Another use case is to compare the changes of same environment periodically. For example, if configuration is saved from production environment once a month, you can use CTT to see configuration changes made to the environment during each month.

Currently, CTT is able to detect changes in template configurations, for example added classes and attributes or changes in attribute configuration. CTT can also show differences in folder structure and roles. Differences in the configuration are highlighted in CTT.

Example Use Cases for CTT

Ensuring Changes Are Correctly Transferred from a Test to a Production Environment

Ensuring that all changes are correctly transferred from a test environment to a production environment when a change is first built and tested with a test environment.

Configuration is usually built in a test environment before implementing the same configuration in a production environment. The first use case for CTT is to compare the configuration between the two environments and make sure all changes built in the test environment are re-implemented into the production environment.

Refreshing a Test Environment to Match the Configuration in Production Environment

Test environments are some times needed to be refreshed to match the production before a new development is started. This might be because of change in plans and not going live with some planned development items. CTT can be used in these cases to check if something is missing or changed in test and help to get the environments to same level before next development item is started.

Versioning the Configuration While Developing It

It is a good practice to take an export from a configuration before starting new feature development and also occasionally, during the development. CTT can be used to compare these versions of the same environment to visualize the progress or help to understand what is done/needs to be done for the development. It is also easier to debug changes with CTT if more complex problems occur.

Currently Supported Configuration Items

As of the current version, CTT provides the support for comparing/transporting the following configuration items:

Unsupported Items

Currently, CTT does not support visualizing or transporting of deleted objects such as templates, classes, or attributes. Thus, importing a CTT generated configuration file to ESM will not remove any template, class, or attribute from the target configuration.

Since comparison of the changes in CTT rely on the codes of the object (such as attribute codes), CTT is not able to detect changes in such codes. For example, an attribute with a changed code is shown as a new attribute in CTT.

Currently, CTT has no capability to detect shared attributes in non-shared classes. This means, that if such attributes are transported, those will be created as new attributes in the target system.

For attributes, transporting of most of the handler configurations are supported. Handler configuration that are not part of the attribute metadata is not supported. This includes, for example, EntityStateMail mail templates.

Step-by-Step Guide

1. Exporting configurations     
   Export configurations from source and target ESM environments (usually test and production) through Maintenance → System settings → Export configurations. Select all applicable configuration item types (under Efecte configurations).

2. Using CTT
   1. Open the CTT application.
   2. Upload exported configurations to CTT, select view changes.
      1. Upload screen should display immediately after opening the application. If upload screen is not open, click on Upload Files in the header to open it.

Source should be the configuration file containing changes. Usually this is the configuration file from an test environment. Target is usually the configuration from current production. You can upload configuration in XML or ZIP format. 
Note: for large configuration files, ZIP format is preferable since it reduces the time to upload the files. Combined file size must be under 150 MB.

3. What you can see in CTT
   1. Differences in templates     
      All templates that have changes are shown in the left side menu. Each template, class and attribute that is either new (green) or changed (yellow) is shown in the menu. If nothing is changed in the template, class or attribute, it’s not shown. (Note: currently removed items are not shown/supported.)     
      
      Selecting an attribute (click attribute name) will show the changes to that attribute in the comparison view:

b. Differences in listeners     
All templates that have new or changed listeners are shown in the left side menu. Select a listener to view the change details.

c. Differences in folders    
New folders (green) and changed folders (yellow).

d. Differences in roles     
New roles (green) and changed roles (yellow). Note: changing role’s template, folder or attribute permissions are not supported as a change yet.

4. Selecting changes and creating configuration file
   1. Select changes by ticking checkbox (Note: currently only templates/classes/attributes can be selected).
   2. Click Apply changes.
   3. A dialog opens where you can see if there are any problems or warnings with the generated configuration file. Click Download configuration file to download the generated configuration file.     
       

5. Importing generated configuration to ESM     
   Note: Import of CTT created configuration file to ESM is supported starting from ESM 2023.3. See also Admin Practices below for requirements.     
    

Filters and Search

In the left side, above the Changes-tree, you can find functionalities to filter and search data. Note that filters and search only affect what is shown in the left side (tree of changes). If you have selected some changes that are hidden due to a filter or search, they will still remain selected.

State Filters

State filters are available for all types of configuration items - templates, folders and roles. By unchecking a filter, it will hide those type of changes from the view. Note that for changed items, it will not hide changed items like templates or classes, if they have new items under them.

Property Filters

Special property filters can be used with templates. By unchecking a filter, it will hide those changes that contain only such type of change. For example, with localizations, if there is only a change in localization (added/changed translations) in an attribute, the attribute will be hidden when filter is used. If the attribute contains localization changes and some other changes, it will not be hidden.

Order

Order refers to class or attribute order numbers in the template. By unchecking this filter, those changes are hidden from the view where the sole change is to the order number.

Localization

Localization refers to added/changed translations for templates, classes and attributes. By unchecking this filter, those changes are hidden from the view where the sole change is to the localization.

Search

Search can be used with templates where you can use it to filter the view. You can use names or codes to search for templates, classes and attributes. Search can be used in combination with filters. To clarify, search only displays results from changes that are not hidden by the filters.

Document of the selected changes

You can download a PDF document containing all the selected changes for templates, classes, and attributes. After selecting the relevant changes, select Apply changes. Then, select Download documentation file:

Admin Practices When Using CTT

• CTT is designed to support use cases, where changes are made through the source environment. Modifying the target environment without CTT import might break some capabilities upon importing.
• ESM must have platform setting configuration.import.update set to true to enable updating of the configuration in configuration import with configuration file generated by CTT
  • CTT also produces a marker in the generated configuration file, which must be present for the import.
  • Without the platform setting and file marker, the configuration import works as it has been working before - it only creates new objects and does not update anything (useful for importing a whole configuration to an empty database)
• All objects in the configuration must have codes defined: templates, classes, attributes, static values, folders, roles etc. CTT uses codes to match objects and find differences in the configuration.
  • ESM functionality in Maintenance → System settings → Run system check can be used to find and add codes for attributes.
  • To be able to add codes for roles, platform setting adminrole.code.editable must be set to true.
• While updating the name of a listener to include a date or version number is current best practice, currently you can only see differences of a changed listener if the name is kept the same.
  • Same applies for other objects that are only identified by name (template events, dashboards, views, scheduled tasks)
    • Note: CTT currently does not support aforementioned objects. Support may be added in future versions.
• Static values need to have codes for them to work with CTT.