Configuration
PowerTSM components read their settings from a hierarchical configuration that can be supplied by several configuration sources. This page describes the supported configuration sources, how the configuration paths used in this documentation map to each source, where configuration files are located, how additional configuration files are included and which settings take precedence when multiple sources are used.
Configuration Sources
Section titled “Configuration Sources”The following configuration sources are supported:
- XML files
- JSON files
- Environment variables
- In-memory key-value pairs
- Command-line arguments
- Custom
IConfigurationSourceimplementations
The configuration is divided into sections corresponding to the module that is being configured. Currently, the following sections support one or more configuration keys:
Configuration– allows including other configuration sources.Persistence– configures the repositories used for persistent data storage.DependencyInjection– registers additional services or replaces existing ones.Cryptography– configures the encryption and decryption of sensitive information.Logging– specifies how components of the PowerTSM .NET API output log messages.Security– configures authentication and authorization.TSM– anything related specifically to time series, such as default settings for time zones.
By default, no configuration is required. However, some features – even basic ones – need some configuration. For example, in order to use encrypted passwords for repositories in your configuration, you need to specify a certificate to use for encryption and decryption.
Certificate for encryption and decryption
Section titled “ Certificate for encryption and decryption”<?xml version="1.0" encoding="utf-8"?><HAKOM> <Cryptography> <CertificateStorage> <LocalUser> <Certificates> <Certificate Name="Default"><!--SHA-1 thumbprint of locally installed certificate.--></Certificate> </Certificates> </LocalUser> </CertificateStorage> </Cryptography></HAKOM>Configuration Paths and Root Elements
Section titled “Configuration Paths and Root Elements”This documentation identifies every setting by its full configuration path, with sections separated by colons, for example HAKOM:TSM:Calculation:Formulas:CustomFunctions:Path. The leading HAKOM is represented differently in each source:
- XML files have a root element. By convention it is
<HAKOM>, but its name is ignored: the sections below the root element (for example<TSM>) form the configuration. - JSON files have no root element. The top-level keys of the JSON object are the sections below
HAKOM(for example"TSM"). Do not wrap the content in a"HAKOM"object. - Environment variables use the
HAKOM__prefix, followed by the rest of the path with sections separated by two underscores (__). The prefix is removed when the variables are read.
The same setting in XML, JSON and environment variables
Section titled “ The same setting in XML, JSON and environment variables”<HAKOM> <TSM> <Calculation> <Formulas> <CustomFunctions> <Path>functions/foo</Path> </CustomFunctions> </Formulas> </Calculation> </TSM></HAKOM>{ "TSM": { "Calculation": { "Formulas": { "CustomFunctions": { "Path": "functions/foo" } } } }}HAKOM__TSM__Calculation__Formulas__CustomFunctions__Path=functions/fooWhere Configuration Files Are Located
Section titled “Where Configuration Files Are Located”By default, PowerTSM applications look for a HAKOM.xml file in their current directory. When an application references the .NET API, the configuration system also checks the directory of the referenced DLL files.
If none is found, it attempts to find a HAKOM.xml file in any of the following locations (in the given order):
%ProgramW6432%\HAKOM%ProgramFiles(x86)%\HAKOM/etc/hakom/usr/share/hakomIncluding Additional/Shared Configuration
Section titled “Including Additional/Shared Configuration”It may be useful to share some configuration between applications or manage some of the settings in separate files. To this end, you can include additional configuration sources from any other source by using the HAKOM:Configuration:Include section.
The section Configuration Using Different Sources below includes examples on how to:
- Include a JSON file from an XML configuration file.
- Include an XML file from a JSON configuration file.
- Include environment variables with a specific prefix from an XML configuration file.
When including a file (either XML or JSON), the FileName setting may contain either a relative or an absolute path. In the former case, the application attempts to find the file in the same manner as it attempts to locate the initial HAKOM.xml file (see Where Configuration Files Are Located above).
Precedence of Settings When Using Multiple Configuration Sources
Section titled “Precedence of Settings When Using Multiple Configuration Sources”When using multiple sources that contain overlapping settings, it is important to understand how these settings are applied.
Assume the following HAKOM.xml:
<?xml version="1.0" encoding="utf-8"?><HAKOM> <Configuration> <Include> <Json> <FileName>C:\GlobalConfig.json</FileName> <Optional>false</Optional> </Json> </Include> </Configuration> <SomeSetting>Value1</SomeSetting></HAKOM>And the file C:\GlobalConfig.json with the following content (without a root element, see Configuration Paths and Root Elements):
{ "SomeSetting": "Value2"}Both files specify a different value for SomeSetting. In this case, the value set in HAKOM.xml is overwritten by the value in GlobalConfig.json, because the included file is inspected after the XML file.
Configuration statement order is not significant
Section titled “ Configuration statement order is not significant”It is tempting to think that the order of statements in the configuration file makes a difference, but it does not. Changing the XML file like this:
<?xml version="1.0" encoding="utf-8"?><HAKOM> <SomeSetting>Value1</SomeSetting> <Configuration> <Include> <Json> <FileName>C:\GlobalConfig.json</FileName> <Optional>false</Optional> </Json> </Include> </Configuration></HAKOM>does not change the behavior described above. This is done on purpose to ensure consistent behavior across sources in which the order of settings cannot be guaranteed (for example environment variables).
Precedence of Settings When Using Default Configuration Sources
Section titled “Precedence of Settings When Using Default Configuration Sources”By default, the .NET API loads configuration from two (optional) sources:
- A
HAKOM.xmlfile (see Where Configuration Files Are Located). - Environment variables starting with
HAKOM__(that is two underscores).
Because environment variables are inspected after the contents of the XML file, for all settings present in both sources, the value specified in the environment variables overwrites the value specified in the XML file.
Configuration Using Different Sources
Section titled “Configuration Using Different Sources”XML configuration files have a root element followed by the settings in their respective sections. By convention, the root element is <HAKOM>; its name is ignored.
Including a separate JSON configuration file
Section titled “ Including a separate JSON configuration file”<?xml version="1.0" encoding="utf-8"?><HAKOM> <Configuration> <Include> <Json> <FileName>C:\HAKOM.json</FileName> <Optional>false</Optional> </Json> </Include> </Configuration></HAKOM>JSON configuration files have no root element: the top-level keys are the sections below HAKOM (for example "Configuration" or "TSM").
Including a separate XML configuration file
Section titled “ Including a separate XML configuration file”{ "Configuration": { "Include": { "Xml": { "FileName": "YetMoreConfiguration.xml", "Optional": "true" } } }}In this case, the file name is relative, so the configuration system looks for it in the same paths as described above under Where Configuration Files Are Located.
It is possible to use environment variables for configuring a service instead of providing a HAKOM.xml file. This is especially useful in containerized environments, for example when using Docker. Detailed information on environment variables in Docker can be found in the Docker run reference.
Any setting and even entire sections may be provided as an environment variable. The name of an environment variable consists of the HAKOM__ prefix followed by the configuration path of the setting below HAKOM, with sections separated by two underscores (__) instead of the colon (:) used in configuration paths:
HAKOM__Cryptography__CertificateStorage__LocalUser__Certificates__Certificate__Default=%SHA1ThumbprintOfLocallyInstalledCertificate%Environment variables with the HAKOM__ prefix are used by default. For flexibility, especially on systems where multiple applications requiring different configurations are run, you may include variables with other prefixes as well.
Including environment variables with a custom prefix
Section titled “ Including environment variables with a custom prefix”<?xml version="1.0" encoding="utf-8"?><HAKOM> <Configuration> <Include> <EnvironmentVariables> <Prefix>MY_APP__</Prefix> </EnvironmentVariables> </Include> </Configuration></HAKOM>This configuration additionally includes any settings from environment variables that start with MY_APP__.
When using the .NET API, you may include configuration from a simple System.Collections.Generic.Dictionary<string, string>. The keys are configuration paths below HAKOM:
Dictionary<string, string> configuration = new(){ ["Cryptography:CertificateStorage:LocalUser:Certificates:Certificate:Default"] = "51e5e51363c9d1f76c0078aaae45512f7e7f3660"};
var tsm = ITsm.Create((container) =>{ container.UseConfigure(configurationBuilder => { configurationBuilder.AddInMemoryCollection(configuration); });}, true);This option allows configuring PowerTSM applications directly at startup via command-line arguments.
TSM.ConsoleExample.exe \ --HAKOM:Cryptography:CertificateStorage:LocalUser:Certificates:Certificate:Default:Name="Default" \ --HAKOM:Cryptography:CertificateStorage:LocalUser:Certificates:Certificate:Default="ffee11a3f567aaf4531"Last but not least, it is also possible to add a custom IConfigurationSource, which is used as configuration when creating the ITsm instance.
var tsm = ITsm.Create((container) =>{ container.Configure(configurationBuilder => { configurationBuilder.Add(myCustomConfigurationSource); });}, true);The pages in this section describe in detail what can be configured in each section, with examples for XML, JSON and environment variables.