Skip to content
Documentation

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.

The following configuration sources are supported:

  • XML files
  • JSON files
  • Environment variables
  • In-memory key-value pairs
  • Command-line arguments
  • Custom IConfigurationSource implementations

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.

flask 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>

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.

flask 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>

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

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.

flask 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:

  1. A HAKOM.xml file (see Where Configuration Files Are Located).
  2. 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.

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.

flask 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>

The pages in this section describe in detail what can be configured in each section, with examples for XML, JSON and environment variables.

© 2026 Volue.Version v0.6.38017 November 2026