Using transformation files

1021 views 2

What transformation files do and how to create and use them.

Overview

Transformation files are used for all system-level configuration (configuration not done through the Admin Panel). By using some relatively simple rules explained in this article you can override any default configuration that is available.

The configurable parts of Atomia are defined in various XML configuration files that you can find in multiple locations of your system. All of these XML files can have one or more files that specify the environment-specific configuration referred to as transformation files, or simply transformations. The syntax of the transformation files is based on the standard web.config transformation syntax developed by Microsoft and commonly used in .NET applications (https://msdn.microsoft.com/en-us/library/dd465326(v=vs.100).aspx).

Locating configuration files

The Atomia Platform consists of multiple applications that each have multiple configurable parts. In order for you to get a better understanding of where to find them and what they do, we have listed a short reference of the most commonly changed configuration files below.

Admin Panel

Location: C:\Program Files (x86)\Atomia\AdminPanel

  • Web.config. Application configuration
  • \bin\*.config. Plugin configuration

Automation Server

Location: C:\Program Files (x86)\Atomia\AutomationServer\Common

  • Resources.xml. Defines all available resources (agents, web servers, etc)
  • ProvisioningDescriptions\ProvisioningDescription.xml. The main file that defines provisioning of services
  • Modules\*.config. Provisioning modules configuration.

Billing APIs

Location: C:\Program Files (x86)\Atomia\BillingAPIs\AccountApi

  • Web.config. Application configuration

Location: C:\Program Files (x86)\Atomia\BillingAPIs\BillingApi

  • Web.config. Application configuration
  • \bin\*.config. Plugin configuration

Billing Customer Panel

Location: C:\Program Files (x86)\Atomia\BillingCustomerPanel

  • Web.config. Application configuration
  • App_Data\appConfig.config. Theme selection, routes and menus
  • \bin\*.config. Plugin configuration

Atomia Common

Location: C:\Program Files (x86)\Atomia\Common

  • unattended.ini. Main Atomia configuration file for environment-specific information

Hosting Control Panel

Location: C:\Program Files (x86)\Atomia\HostingControlPanel

  • Web.config. Application configuration
  • App_Data\appConfig.config. Theme selection, routes and menus
  • \bin\*.config. Plugin configuration

Identity

Location: C:\Program Files (x86)\Atomia\Identity\STS

  • Web.config. Application configuration

Store

Location: C:\Program Files (x86)\Atomia\Store

  • Web.config. Application configuration
  • \bin\*.config. Plugin configuration

Creating a transformation file

All configuration files that allow modifications have an unmodified copy of itself in a folder called Original Files. The copy is located at the same level in the file system as the original configuration file. In this location, there is also a folder called Transformation Files, in which all transformation files for files in the current file system level are placed.

[Original Files]
   Resources.xml
[Transformation Files]
   Resources.MyChanges.xml
Resources.xml

Your transformation file should be named with a descriptive identifier prepended, like the original configuration file. See the example above, in which the file Resources.xml is transformed with the file Resources.MyChanges.xml. The transformation application that performs the actual transformations traverses the file system, searching for files by these rules in the described locations.

Writing the transformation

Consider the following simple XML file:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="appConfig" type="Atomia.Web.Base.Configs.AppConfig, Atomia.Web.Base" />
  </configSections>
  <appConfig xmlns="Atomia.Web.Base.Configs">
    <pluginSettingsList>
      <pluginSettingsPlugin pluginName="VPS">
        <pluginSetting name="PasswordLength" value="8" />
        <pluginSetting name="PasswordNonAlpha" value="1" />
      </pluginSettingsPlugin>
    </pluginSettingsList>
  </appConfig>
</configuration>

In this example, we want to modify the PasswordLength to 16, instead of the default value of 8, by the means of creating a transformation file. The file is called “Atomia.Web.Plugin.VPS.dll.config” (a plugin to Hosting Control Panel) and is found in the folder “C:\Program Files (x86)\Atomia\HostingControlPanel\bin”.

Create a new file: C:\Program Files (x86)\Atomia\HostingControlPanel\bin\Transformation Files\Atomia.Web.Plugin.VPS.dll.ChangePasswordLength.config. Add the following content to it:

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <appConfig xmlns="Atomia.Web.Base.Configs">
    <pluginSettingsList>
      <pluginSettingsPlugin pluginName="VPS">
        <pluginSetting name="PasswordLength" value="16" xdt:Locator="Match(name)" xdt:Transform="SetAttributes(value)"/>
      </pluginSettingsPlugin>
    </pluginSettingsList>
  </appConfig>
</configuration>

In this example, we copy the structure of the XML (removing the non-essentials) and define the section to be changed by the means of xdt locator and xdt transform.

We specify that this is a section that contains XML-Document-Transforms:

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">

This is the actual transformation that is being done. By using the xdt:Locator syntax we will find the entry within the current level of the XML that has the same name attribute. With xdt:Transform we define that we want to update the attribute value.

<pluginSetting name="PasswordLength" value="16" xdt:Locator="Match(name)" xdt:Transform="SetAttributes(value)"/>

The same transformation can also be simplified to one line, by using an XPath expression to locate the row to change:

<?xml version="1.0" encoding="utf-8"?>
<pluginSetting name="PasswordLength" value="16" xdt:Locator="XPath(//*[@name='PasswordLength'])" xdt:Transform="SetAttributes(value)" xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform"/>

For more information about the syntax, see https://msdn.microsoft.com/en-us/library/dd465326(v=vs.100).aspx

Useful tip

After every transformation file creation/update, the change needs to be merged to the main configuration file. That can be done by executing a shortcut Recreate config files.lnk that exists in every atomia application folder, e.g. C:\Program Files (x86)\Atomia\HostingControlPanel\Recreate config files.lnk. There is also a PowerShell script that can be used to execute all recreate shortcuts on the server at once: C:\install\recreate_all_config_files.ps1.

Useful tip

In order to make sure that new configuration changes are loaded properly into Atomia applications, the best thing is to restart Atomia by restarting IIS and Atomia windows services. Here is a small batch script that can be used as a reference how to do the restart easily: restart-atomia.zip

Was this helpful?