TSM Data Interface

Introduction

The HAKOM Data Interface Console is a general interface for HAKOM databases, offering the following main functions:

• Import time series from CSV files into a database in the HAKOM time series format.
• Export of time series data from a database into a configurable CSV file.
• Import XML files into a database in HAKOM time series format.
• Export of time series data from a database into an XML file.

Using the Data Interface

The HAKOM Data Interface functionality is accessible via console commands and offers a wide variety of configuration options. All available settings may be found here: Data Interface Configuration

Before running an import or export process it is necessary to prepare the configuration file that's to be used and tailor it to the specific import file or the desired export file.

CSV Import

CSV imports are initiated via a console command. The following parameters are available:

Examples

A standard import run:

HAKOM.Framework.DataInterface.Console.exe import csv -c {Name_of_configuration_file}

An import run with an additional parameter, defining the column of an import file that the value of a time series data point is located in:

HAKOM.Framework.DataInterface.Console.exe import csv -c {Name_of_configuration_file} -p ValueColumn=3

The corresponding configuration file has to also include all individual parameters in order for this feature to work. More information on how to adjust the configuration file can be found here: Data Interface Configuration

CSV Export

CSV Exports are initiated via a console command. The following parameters are available:

Example

HAKOM.Framework.DataInterface.Console.exe export csv -c {Name_of_configuration_file} -i {ID_of_time_series} --from {from_date_in_ISO_8691} --to {to_date_in_ISO_8691}

XML Import

In order to import XML files the import files need to be prepared in the following format:

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfTimeSeries xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.hakom.at">
	<TimeSeries>
		<TimeSeriesDefinition>
			<ID>-1</ID>
			<Name>Time Series Name</Name>
			<Description>Time Series Description</Description>
			<Schema>ZAMS</Schema>
			<Table>FWT_TSDATA</Table>
			<ArchiveTable>FWT_TSDATAARCHIVE</ArchiveTable>
			<Type>A</Type>
			<IntervalName>H</IntervalName>
			<IntervalLength>1</IntervalLength>
			<Unit>kWh</Unit>
			<Formula></Formula>
			<Attributes>
				<TimeSeriesAttribute>
					<Name>Test_Attribute</Name>
					<Value>123</Value>
				</TimeSeriesAttribute>
			</Attributes>
			<ExchangeTimeSeries>
				<arr:string>Exchange_Time_Series</arr:string>
			</ExchangeTimeSeries>
		</TimeSeriesDefinition>
		<ArrayOfTimeSeriesData>
			<TimeSeriesData>
				<From>2021-01-01T00:00:00</From>
				<To>2021-01-01T01:00:00</To>
				<Value>1234</Value>
				<Flag>9</Flag>
			</TimeSeriesData>
			<TimeSeriesData>
				<From>2021-01-01T01:00:00</From>
				<To>2021-01-01T02:00:00</To>
				<Value>1235</Value>
				<Flag>9</Flag>
			</TimeSeriesData>
			<TimeSeriesData>
				<From>2021-01-01T02:00:00</From>
				<To>2021-01-01T03:00:00</To>
				<Value>1236</Value>
				<Flag>9</Flag>
			</TimeSeriesData>
		</ArrayOfTimeSeriesData>
	</TimeSeries>
</ArrayOfTimeSeries>

The import process is started via a console command. The following parameters are available:

Example

HAKOM.Framework.DataInterface.Console.exe import xml -d {Database_connection} -s {Import_file}

When importing an XML file that contains the time series id "-1" a potentially already existent time series will be overwritten. Setting the time series id as "-2" in the import file will result in an error message if a time series with the same name already exists.

XML Export

The XML Export exports time series master data in addition to time series data points.

An export process can be started via a console command. The following parameters are available:

Example

HAKOM.Framework.DataInterface.Console.exe export xml -d ZAMS -t XML_Export -i 1 --from 1 --to 2

XML Convert

Using the command "convert xml" it is possible to convert XML files containing time series data which does not correspond to the HAKOM format into the HAKOM format with the help of an XSLT transformation file.

The convert process can be started via a console command. The following parameters are availabe:

Example

HAKOM.Framework.DataInterface.Console.exe convert xml -s XML_Source -t XML_Target -x XSLT_File

Logging

Import and export activities via the Data Interface are logged according to the configured settings. For more information on configuration options please refer to: Data Interface Configuration

Via the HAKOM Log Monitor it is possible to view existing log entries by data source and log source suffix as well as filter the entries by additional categories like date, type, user, etc.

More detailed information regarding the HAKOM Log Monitor can be found here: Log Monitor

Details on successful and failed imports and exports can be found here as well as further information relating to individual Data Interface runs.

Examples

A few different examples of configuration and import files are provided as part of the installation of the HAKOM Data Interface. The example files can be found in the folder "Examples" located in the installation directory.

These examples provide an overview of possible configuration scenarios and demonstrate the relation between a configuration file and the corresponding import file.