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