Documentation Portal

When this step is done you will have a custom connector up and running and successfully connected to TrendMiner.

You can implement your custom connector with your preferred technology. The standard TrendMiner connector is a .NET application, deployed in Microsoft IIS, but other options can be Java, NodeJS, … deployed standalone or to the cloud e.g. AWS Lambda, Azure functions, …

To get to an MVP (minimal viable product) version of your connector a few REST API endpoints need to be implemented. The first REST endpoint to implement is:

GET /api/version 

Example output:

{ 
    "version": "1.0.0"
}

Which version your connector returns is up to you. You can use the versioning to keep track of your connector updates. TrendMiner only uses this information to display in ConfigHub. After this endpoint is implemented you can add your connector to TrendMiner via ConfigHub (check the user documentation to find out how).

If your connector is added successfully, the version will be shown in ConfigHub and you are ready for the next step.

When this step is implemented you will see your provider listed in ConfigHub in the dropdown of available providers. An implementation of this endpoint provides meta data for a specific provider.

It describes what capabilities it has:

The endpoint to implement is:

GET /api/provider

Example output:

[
  {
    "name": "myProvider",
    "label": "My Provider",
    "experimental": false,
    "capabilities": [
      "TIME_SERIES"
    ],
    "properties": [
      {
        "name": "PREFIX",
        "type": "SINGLE_LINE",
        "label": "Prefix",
        "placeholder": "",
        "capabilities": [
          "TIME_SERIES"
        ],
        "required": false,
        "encrypted": false
      },
      {
        "name": "TAGFILTER",
        "type": "SINGLE_LINE",
        "label": "Tag filter",
        "placeholder": ".*BA.*",
        "capabilities": [
          "TIME_SERIES"
        ],
        "required": false,
        "encrypted": false
      },
      {
        "name": "HOST",
        "type": "SINGLE_LINE",
        "label": "Host",
        "placeholder": "Host",
        "capabilities": [],
        "required": true,
        "encrypted": false
      },
      {
        "name": "USERNAME",
        "type": "SINGLE_LINE",
        "label": "Username",
        "placeholder": "",
        "capabilities": [],
        "required": false,
        "encrypted": false
      },
      {
        "name": "PASSWORD",
        "type": "SINGLE_LINE",
        "label": "Password",
        "placeholder": "",
        "capabilities": [],
        "required": false,
        "encrypted": true
      }
    ]
]

ProviderCapabilities

An object that represents a provider capabilities:

ProviderCapabilitiesProperty

An object that represents a provider capabilities property:

When this step is implemented you will see your data source listed in ConfigHub.

One instance of a connector can connect to multiple data sources. The connector should provide an endpoint which returns a list of data sources it connects to. Administrators can then grant users permissions to one or more data sources.

The endpoint to implement is:

GET /api/database 

Example output:

{
    "DbId": 1,
    "Name": "myHistorian",
    "Prefix": "",
    "TagFilter": "",
    "Provider": "myProvider",
    "DataSource": "",
    "UserId": "",
    "Password": "",
    "Version": "",
    "OnlySupportsRawValues": true
    "Properties": []
}

Notes:

Output requirements:

If this endpoint is implemented successfully you can verify if your data source is visible in ConfigHub. Navigate to "Data sources" in the left menu and check if your data source shows up.

{
  "healthy": true
}

If you want to be able to add new datasources from ConfigHub, this endpoint should be implemented as well.

POST /api/database 

The request body that will be sent will be of the following structure and needs to be processed by the connector so that the datasource is added.

{
    "Name": "myHistorian",
    "Prefix": "",
    "TagFilter": "",
    "Provider": "myProvider",
    "DataSource": "",
    "UserId": "",
    "Password": "",
    "Version": "",
    "OnlySupportsRawValues": true
    "Properties": [
        "key": "value",
         ...
    ]
}

If there are no additional properties to pass on, then the "Properties" attribute itself should not be passed on. Upon successful creation, the endpoint should return a 200 response returned the id of the newly created datasource.

When this step is implemented your tags will be accessible in TrendHub.

A 'tag' refers to one time series. TrendMiner requires the metadata of all tags to be known before they can be used. All tags in one data source need to be returned in a flat list. The tags query should accept one query parameter which will be passed on to the next endpoint which needs to be implemented for your custom connector:

Parameter:

Example query:

GET /api/v2/tags?historianName=<historianName> 

where <historianName> is value of the "Name" field returned by the GET /api/database call.

Example output:

[
  {
    "Name": "React5_temp001",
    "Description": "Reactor 5 - Cooling water temperature",
    "Units": "C",
    "Type": "ANALOG"
  },
  {
    "Name": "React5_press",
    "Description": "Reactor 5 - Top pressure",
    "Units": "",
    "Type": "ANALOG"
  },
  {
    "Name": "React5_phas",
    "Description": "Reactor 5 - Production Phases",
    "Units": "",
    "Type": "STRING"
  }
]

Output requirements:

Notes:

When this endpoint is implemented, you'll need to make sure your user has access to this data source before you can find the tags from the data source in TrendMiner. This article describes how you can assign the right permissions.

Also make sure to sync the data source to TrendMiner to make sure the tag list is updated.

Once the right permissions are assigned, log in to TrendHub and you should be able to search your tag names and descriptions in the tag browser. If this looks ok, you're ready for the next step.

When this step is implemented you will be able to visualise your tags in TrendMiner and run analytics on them.

TrendMiner requests values for a given tag in a specific time period while indexing data. Implementations of the Connector API can choose to either return raw values, or implement an analytics optimization. Implementing the analytics optimization is only recommended when the data source natively supports generating plots.

Four query parameters are important:

The other query parameters are relevant for the plot optimized representation only and can be ignored in a first POC implementation.

Example query:

GET /api/v2/tags/indexvalues?historianName=myHistorian&tagName=React5_temp001&tagType=ANALOG&interpolationType=DEFAULT&startDate=2021-01-01T00:00:00Z&endDate=2021-02-01T00:00:00Z&numberOfIntervals=44640' 

Example output:

[
{
	"Ts": "2021-01-01T00:00:00.0000000Z",
	"Value": "73.1889496"
},
{
	"Ts": "2021-01-01T00:31:24.0000000Z",
	"Value": "85.7846146"
},
{
	"Ts": "2021-01-01T01:31:24.0000000Z",
	"Value": "98.4507751"
},
{
	"Ts": "2021-01-01T02:31:24.0000000Z",
	"Value": "98.1346054"
},

...

{
	"Ts": "2021-01-31T20:44:54.0000000Z",
	"Value": "3.7891531"
},
{
	"Ts": "2021-01-31T21:57:54.0000000Z",
	"Value": "24.2102547"
},
{
	"Ts": "2021-02-01T00:00:00.0000000Z",
	"Value": "73.1889496"
}
]	    

Each data point in the response contains two fields:

The Index values response needs to adhere to some specific rules:

When this endpoint is implemented, the tags can be indexed in TrendMiner. Tag indexing will start as soon as the tag is added to the active tag list. If the tag was already added before the tag indexing status might be on 'failed' and you might need to manually trigger re-indexing.

Once the tag is indexed it can be visualized on the chart and it can be used in analyses.