Configuration

Configuration Using HAKOM.Config

In case the standard installation procedure is used, the HAKOM.Config is deployed to the local binary folder. Alternatively it is also possible to use a central HAKOM.Config file located on a network drive. In order to use a central HAKOM.Config, the following details must be entered in the local HAKOM.Config.

<HAKOMConfiguration>
	<ConfigLocation Type="Path" Location\\networkdrive\product\HAKOM-TSM " />
</HAKOMConfiguration>

The HAKOM.Config provided by the installation contains the minimum configuration required to run the TSM App. There are many additional settings available to customise the behaviour of the TSM App, which are described here and the subsequent pages.

The HAKOM.Config is an XML file, structured hierarchically and is divided into three main parts:

• Database connections: <dbconnections>
• HTTP connections: <HttpConnections> Only supported in TSM App.
• Products: <products>

<HAKOMConfiguration>
	<dbconnections>
		<!-- Configuration of database connections. -->
	</dbconnections>
    <HttpConnections>
        <!-- Configuration of HTTP data sources. Only supported in TSM App. -->
    </HttpConnections>
	<products>
		<!-- Settings for specific products. -->
	</products>
</HAKOMConfiguration>

Database Connections

On this level database connections may be configured.

The individual database connections are listed hierarchically under the tag "<dbconnections>. The name of a database connection may be chosen freely.

• <cnn> contains the connection string, depending on the database
• <password> the password can be entered unencrypted. In that case, it is encrypted the first time the application is used and saved in the HAKOM.config. To encrypt a password beforehand, the Password Encryption Console can be used to encrypt a password. 

Below you can find examples for all supported databases:

<HAKOMConfiguration>
	<dbconnections>
		<OracleManaged>
			<cnn>User ID=TSM;Data Source=TEST;Persist Security Info=False;Min Pool Size=0;Schema=TSM</cnn>
			<password>XpwYr2garEE=</password>
			<provider>HAKOMOracleManaged</provider>
		</OracleManaged>
		<SQLServer>
			<cnn>User ID=TSM;Data Source=TEST;Integrated Security=false;Initial Catalog=TSM;Min Pool Size=0;MultipleActiveResultSets=True;CommandTimeout=30</cnn>
			<password>XpwYr2garEE=</password>
			<provider>SQLDBClient2008</provider>
		</SQLServer>
		<PostgreSQL>
			<cnn>Server=TEST;Port=5432;Database=TSM;User Id=TSM;Pooling=true;Command Timeout=30</cnn>
			<password>XpwYr2garEE=</password>
			<provider>HAKOMPostgreSQL</provider>
		</PostgreSQL>
	</dbconnections>
</HAKOMConfiguration>

Command Timeout for SQL Server

For SQL Server connection strings it is possible to configure a "CommandTimeout" in order to limit the runtime of individual database queries. An example can be found above.

If this setting is not configured, the default value will limit the runtime of queries to 30 seconds.

Connection Pooling

For all three database types, connection pooling should be activated to achieve optimal performance. By default it is activated for Oracle, SQL Server and PostgreSQL.

Password Encryption Console

If the database password is entered unencrypted in the configuration, it will be encrypted and replaced in the HAKOM.Config file the first time it is read by the application. In some cases, this may be inconvenient (eg. if the configuration is provided by environment variables or the HAKOM.Config is stored in a folder without write permissions). For this purpose the Password Encryption Console encrypts a password which can be stored as an encrypted database password in the configuration file or an environment variable.

To encrypt a password with the Password Encryption Console, open a CLI in the folder where the HAKOM.Framework.Encryption.Console.exe is located and run the executable with the password as the argument. The returned value is the encrypted password. 

Usage:
  HAKOM.Framework.PasswordEncryption.Console <password> [options]

Arguments:
  <password>  The password to encrypt.

Options:
  --version       Show version information
  -?, -h, --help  Show help and usage information

Windows

HAKOM.Framework.PasswordEncryption.Console.exe SuperSecretPassword

Linux

dotnet HAKOM.Framework.PasswordEncryption.Console.dll SuperSecretPassword

HTTP Connections

Accessing data from a webservice instead of a database is only supported in the TSM App.

In order to access data from a webservice instead of directly from a database, it is possible (starting with version 3.10.0) to configure HTTP data sources as well.

These must be instances of either HAKOM WebTSM Services (HAKOM time series webservice version 3.x) or HAKOM HTTP API (HAKOM time series webservice version 4 and above).

Minimum Configuration

<HAKOMConfiguration>
  <HttpConnections>
    <HttpConnection Id="WebTSMServices" Name="WebTSM Services">
      <ApiRoot><!-- insert the URL of the service here. --></ApiRoot>
    </HttpConnection>
  </HttpConnections>
<HAKOMConfiguration>

The ApiRoot element is required and should be a URL that points to the root of the service. That is, when copying the URL under ApiRoot into a Webbrowsers address-bar, it should return the version info of the service similar to this:

{"Name":"PowerTSM® HTTP API","Description":"A powerful and FeasyUse® enabled HTTP API for managing time series.","Version":"3.9.2.7+clr29056"}

Authentication

Usually, accessing a webservice as a data source requires some form of authentication.

At the moment, only OpenIDConnect authentication using Azure Entra ID is supported and is configured as the following example shows:

<HAKOMConfiguration>
	<HttpConnections>
		<HttpConnection Id="PowerTSMCloud" Name="PowerTSM Cloud">
			<ApiRoot>https://api.powertsm.com/api</ApiRoot>
			<Authentication Type="Microsoft">
				<TenantId><!-- insert tenant here --></TenantId>
				<ClientId><!-- insert client id here --></ClientId>
				<AdditionalScopes><!-- insert any additional required scopes here (openid and profile will always be requested) as a list of space separated strings.</AdditionalScopes>
				<AllowUsingCurrentOSUser><!-- whether to attempt to use the currently logged in user instead of explicitly prompting for credentials. Possible value: true/false. --></AllowUsingCurrentOSUser>
			</Authentication>
		</HttpConnection>
	</HttpConnections>
</HAKOMConfiguration>

Products

Settings regarding different HAKOM products can be configured in this section. Generals settings for the HAKOM Framework are descripted in the following section.

Specific settings for other applications and plug-ins can be found on the pages listed below.

• TSM App Configuration
• WebTSM Services API Configuration
• Time Series Plug-in Configuration
• Master Data Import/Export Plug-in Configuration
• Automation Plug-in Configuration

HAKOM Framework

In the following table all available general settings for the HAKOM TSM are descripted.

They are located under following base path in the XML structure of HAKOM.config: //HAKOMConfiguration/products/HAKOMFramework/settings

Assembly Cache

The assembly cache can be activated to accelerate the evaluation of formula time series.

The functions in the EvalComponent*.vb files are compiled into a temporary DLL at every function call. To save the required time for this process, the following entry can be added to HAKOM.Config.

<HAKOMConfiguration>
	<products>
		<HAKOMFramework>
			<settings>
				<AssemblyCache>%ALLUSERSPROFILE%\HAKOM\TSM\AssemblyCache</AssemblyCache>
			</settings>
		</HAKOMFramework>
	</products>
</HAKOMConfiguration>

The created DLL files are then stored in the configured location and reused until one of the EvalComponent files or the formula itself is changed.

Support of Milliseconds

To activate time series with intervals less than one second, in HAKOM.config the setting InternalTimeUnit must be added or adjusted.

<HAKOMConfiguration>
  <products>
    <HAKOMFramework>
      <settings>
        <InternalTimeUnit>2</InternalTimeUnit>
      </settings>
    </HAKOMFramework>
  </products>
</HAKOMConfiguration>

Possible values:

• 0 (default), seconds, beginn: 1972-01-01T00:00:00+01:00
• 1 seconds, beginn: 1970-01-01T00:00:00Z
• 2 milliseconds, beginn 1970-01-01T00:00:00Z

If the configuration does not contain this tag, the default value 0 will be used.

In addition, a change must also be made to the database. The database contains the function CA_InternalTimeUnit. It returns a fixed value. This return value must be altered with the numeric representation of the required time unit.

BEGIN
	--0: Seconds, HAKOM-Time
	--1: Seconds, Epoch-Time
	--2: Millisecond, Epoch-Time
	RETURN 0;
END;

Configuration Using Environment Variables

It is possible to use environment variables for configuring a service instead of providing a HAKOM.Config file. This is especially useful in containerized environments, for example when using Docker.

Detailed information on environment variables in Docker may be found here: https://docs.docker.com/engine/reference/run/#env-environment-variables

Any setting and even entire sections may be provided as an environment variable. The name of an environment variable must correspond to the location of a setting in the HAKOM.Config file.

<HAKOMConfiguration>
	<products>
		<WebTSMServices>
			<Hosting>
				<Url>http://127.0.0.1/</Url>
			</Hosting>
		</WebTSMServices>
	</products>
</HAKOMConfiguration>

This setting can be configured by the environment variable

"HAKOMConfiguration_products_WebTSMServices_Hosting_Url=http://127.0.0.1/"

By assigning XML tags as the value of an environment variable it is possible to set up multiple configurations:

<HAKOMConfiguration>
	<products>
		<WebTSMServices>
			<Authentication>
				<IntegratedIdentityProvider>
					<ValidClients>
						<Client>
							<Id>TestClient</Id>
							<Secret>Password</Secret>
							<User>TestUser</User>
						</Client>
						<Client>
							<Id>TestClient2</Id>
							<Secret>Password2</Secret>
							<User>TestUser2</User>
						</Client>
					</ValidClients>
				</IntegratedIdentityProvider>
			</Authentication>
		</WebTSMServices>
	</products>
</HAKOMConfiguration>

This configuration may be replaced by the environment variable:

"HAKOMConfiguration_products_WebTSMServices_Authentication_IntegratedIdentityProvider_ValidClients=<Client><Id>TestClient</Id><Secret>Password</Secret><User>TestUser</User></Client><Client><Id>TestClient2</Id><Secret>Password2</Secret><User>TestUser2</User></Client>"

Behavior When Using Environment Variables

• If there is a HAKOM.Config, it will be used
• If none is present, environment variables can be used
• A mix is currently not supported

Link to Configuration File Using Environment Variables

In order to refer to a central HAKOM.Config using environment variables, the following variables must be set: