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 use of environment variables is also possible in the specified path. This means it's possible for multiple users to share a single TSM App installation with individual configuration. Example:

<HAKOMConfiguration>
    <ConfigLocation Type="Path" Location="%USERPROFILE%\Documents" />
</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. 

The following encryption algorithms are supported:

• RSA encryption with X.509 certificate
• DES encryption (obsolete and considered insecure)

If RSA encryption is used, the thumbprint of the installed X.509 certificate must be entered in the HAKOM.Config. The certificate must be installed in the Current User store under Personal, must contain an RSA public key and must be associated with a corresponding private key under the users account.

This is supported on all major platforms (Windows, Linux and MacOS). For an examples on how to generate, install and use an appropriate certificate, please see (3.10.4) Configuration#(3.10.4)Configuration-PasswordEncryption

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 Certificate="51e5e51363c9d1f76c0078aaae45512f7e7f3660">Vy2SdKJSea+ap...YrYsTnkm9Xhw=</password> <!-- RSA encrypted password with X.509 certificate -->
			<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> <!-- DES encrypted 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> <!-- DES encrypted 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

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 HAKOM product package includes a command line tool named  Password Encryption Console which encrypts a password for use 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.

Supported encryption algorithms:

• RSA encryption with X.509 certificate
• DES encryption (obsolete and insecure)

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

Arguments:
  <password>  The password to encrypt.

Options:
  -c, --certificate <certificate>  The SHA-1 thumbprint of an X.509 certificate installed under Current User/Personal
                                   that should be used for encryption.
  --version                        Show version information
  -?, -h, --help                   Show help and usage information

RSA Encryption

Note that for this to work, the following prerequisites must be met:

1. An X.509 certificate must be installed in the Current User store of the operating system, in the Personal folder.
2. The certificate must contain an RSA public key (DSA, ECDSA keys are not supported)
3. The user must have the private key associated with the certificate.

Please contact HAKOM Support if you need help generating an appropriate certificate.

Windows

Installation of the certificate should be fairly straight forward. Documentation of the process can be easily found online. Nonetheless, here is a simple example on how to generate and install a certificate using Powershell:

PS C:\Users\You> $params = @{
>>     Type = 'Custom'
>>     Subject = 'CN=YourName,OU=YourDepartment,O=YourCompany'
>>     KeyUsage = 'DataEncipherment'
>>     KeyAlgorithm = 'RSA'
>>     KeyLength = 2048
>>     CertStoreLocation = 'Cert:\CurrentUser\My'
>> }
PS C:\Users\You> New-SelfSignedCertificate @params

Obviously, the subject fields ("YourName", "YourDepartment", etc) should be replaced with values that are more appropriate.
This will generate and install the certificate in the correct location

   PSParentPath: Microsoft.PowerShell.Security\Certificate::CurrentUser\My

Thumbprint                                Subject
----------                                -------
C26B766FBEA7E5B23E1C44D79BE8F3B8DC9E996F  CN=YourName, OU=YourDepartment, O=YourCompany

You can then encrypt passwords using the generated certificate.

HAKOM.Framework.PasswordEncryption.Console.exe -c C26B766FBEA7E5B23E1C44D79BE8F3B8DC9E996F SuperSecretPassword

 Note that the expiration/validity is NOT checked during encryption or decryption so you DO NOT have to generate a new certificate periodically.

Linux

Generation and installation of the certificate under Linux is somewhat complicated and depends on the exact distribution. Please contact HAKOM Support for assistance.

dotnet HAKOM.Framework.PasswordEncryption.Console.dll -c C26B766FBEA7E5B23E1C44D79BE8F3B8DC9E996F SuperSecretPassword

DES Encryption

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

Assembly Cache for Formula Time Series

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.

Assembly Cache for Ad Hoc Formulas

For ad hoc formulas, similar to formula time series, a temporary DLL is compiled during calculation. This DLL can also be cached. If the same ad hoc formula is called again in the same process, the DLL no longer needs to be compiled. However, old DLLs are deleted in new processes because they are no longer accessible. The “Expiration” setting can therefore be used to prevent recently created DLLs from being deleted by another process.

<HAKOMConfiguration>
    <products>
        <HAKOMFramework>
            <settings>
                <Caching>
                    <AdHocFormulas>
                        <Enabled>false</Enabled> <!-- <Default: false -->
                        <Path>C:\Users\JaneDoe\AppData\Local\Temp\HAKOM Framework Assembly Cache</Path> <!-- Default: “HAKOM Framework Assembly Cache” in System Temp Path -->
                        <Expiration>1.00:00:00</Expiration> <!-- Default: 1.00:00:00 (1 day) -->
                    </AdHocFormulas>
                </Caching>
            </settings>
        </HAKOMFramework>
    </products>
</HAKOMConfiguration>

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: