Skip to content

ABB Knowledge Manager Connector — User Guide

How to deploy, configure, and verify the VirtualForge ABB Knowledge Manager connector. For what the connector is and why it is shaped this way, start with ABB Knowledge Manager Connector for Seeq.

Overview

The connector is a Seeq datasource connector that brings ABB Knowledge Manager (ABB KM) content into Seeq: the tag catalog, the signals, and their time-series history. It runs inside a Seeq Link remote agent and reads from Knowledge Manager over ABB's ExtDataAccess WebAPI.

It is a pull connector, and one connection maps to one Seeq datasource. Sample data is served from Knowledge Manager on demand as users trend and analyze, so Seeq never becomes a second copy of the historian.

Seeq Server
    │
Seeq Link remote agent            ← on your infrastructure
    │
ABB KM connector                  ← one connection per KM server
    │
ABB KM ExtDataAccess WebAPI       ← your Knowledge Manager installation

Indexing is full-only. ABB Knowledge Manager has no change feed — nothing in the source can tell the connector what changed since last time — so each index run rebuilds the catalog rather than applying a delta. The incremental hook that other VirtualForge connectors use is present but inert here, which is a property of the source rather than a gap in the connector. Plan the index schedule accordingly: weekly is the shipped default, and daily is common.

Installation

Prerequisites

  • A Seeq Server with a Seeq Link remote agent
  • Java 21+ on the remote agent host
  • Network reachability from the agent host to the ABB KM ExtDataAccess WebAPI endpoint
  • A Knowledge Manager account the connector can authenticate as, with read access to the tag catalog and tag data
  • A license file issued for the agent host (see Licensing)

Which Seeq version a given release was validated against is stated with that release — see Versions & Seeq Compatibility.

Deployment steps

  1. Obtain the connector ZIP from your Endeavor Engineering contact.

  2. Deploy it to the remote agent — either copy the ZIP to the agent machine and extract it into the agent's connector plugins directory, or use Seeq Admin → Remote Agents → Upload Connector.

  3. Create the configuration file at <agent data folder>/configuration/link/ABB KM Connector V3.json. The connector ships a template at that name with placeholder values; see Configuration file structure.

  4. Install the license. On its first start the connector creates the license folder and writes a host-fingerprint file. Send that file to Endeavor Engineering, then place the license you receive back at the path named in the agent log.

  5. Restart the remote agent.

  6. Verify:

  7. The agent log shows the connector loading, and a license line reading state=LICENSED
  8. In Seeq, under Administration → Datasources, the datasource appears and reports connected
  9. After the first index run completes, the asset tree and its signals appear in Workbench

Licensing

The connector is licensed per host, and the license is bound to a fingerprint of that host — a copied license file fails rather than working somewhere else.

Until a license issued for that host is installed, the connector starts normally, logs its state, and registers zero active datasources. There is no grace window. So an empty asset tree on an otherwise healthy-looking agent is the expected appearance of a missing license, not a fault — check the log before looking anywhere else.

The license is never stored in the configuration file, and its path is resolved outside config. A Seeq configuration reset therefore cannot remove your license.

Configuration file structure

The connector is configured through ABB KM Connector V3.json. The shipped template, with placeholders where your values go:

Leave the Version line exactly as it is. It identifies the file's format, not a product version, and is the same value the legacy connector wrote. Seeq ignores a file whose Version it does not recognize and starts the connector with an empty configuration.

{
  "Version": "com.abbkmv4.seeq.link.connector.ABBKMConnectorConfigV4",
  "VForge": {
    "VirtualForgeEnabled": false
  },
  "Connections": [
    {
      "Name": "ABBKM-Default Connection",
      "Id": "d1c4dade-947e-433b-8187-c31e0500acfd",
      "Enabled": false,

      "Indexing": {
        "Frequency": "1w",
        "OnStartupAndConfigChange": false,
        "Next": null
      },

      "WebServiceMethod": "http",
      "WebServiceIP": "your-abb-km-server",
      "WebServicePort": 80,
      "WebServiceURL": "/ExtDataAccess/api",
      "WebServiceTimeout": 180000,

      "UserName": "VFORGE_SECRETS",
      "Password": "VFORGE_SECRETS",
      "Domain": "VFORGE_SECRETS",

      "HierarchyMode": "tagid",
      "UserTimeZone": "GMT+00:00",

      "VForge": {
        "Http": {
          "MaxRetries": 3,
          "BackoffBaseMs": 200,
          "BackoffMaxMs": 20000,
          "RequestsPerSecond": 0,
          "CircuitBreakerEnabled": true,
          "AdaptiveConcurrency": true,
          "Tls": {
            "Trust": "Any",
            "TrustStore": null
          }
        },
        "Indexing": {
          "IncrementalIndexingFrequency": null,
          "MaxIndexingDuration": "2h",
          "PostFlushSettle": "2s"
        },
        "Monitoring": {
          "Enabled": false,
          "SignalLocation": "FILE_SIGNAL_STORAGE"
        }
      }
    }
  ]
}

The file name and the V3/V4 strings in it are on-disk identifiers, not the product version. They are the literal names Seeq and the connector use to find each other, so renaming them breaks an existing configuration. Leave them as they are. Likewise keep the generated Id — it is what ties this connection to its Seeq datasource across restarts.

Two fields to change first: Enabled ships as false so a freshly deployed connector does nothing until configured, and WebServiceIP is a placeholder. Nothing indexes until both are set. Then give the connection its Knowledge Manager account with vf-agent secrets set (see Credentials); the configuration itself keeps VFORGE_SECRETS.

Configuration parameters

Connection

Parameter Type Required Description
Name String Yes Display name for the connection, and the Seeq datasource name
Id String Yes Unique identifier — keep the generated value
Enabled Boolean Yes Enable or disable this connection. Ships false

ABB Knowledge Manager endpoint

Parameter Type Required Description
WebServiceMethod String Yes "http" or "https"
WebServiceIP String Yes Hostname or address of the Knowledge Manager server
WebServicePort Integer Yes Port the ExtDataAccess WebAPI listens on
WebServiceURL String Yes API path — "/ExtDataAccess/api" unless your installation differs
WebServiceTimeout Integer No Per-request timeout in milliseconds. Default 180000
UserName String Yes VFORGE_SECRETS (the default): take the account from the secrets store. See Credentials
Password String Yes VFORGE_SECRETS (the default). A password written here still works but is deprecated
Domain String No VFORGE_SECRETS (the default). The account's Windows domain is kept in the store with it

Authentication is NTLM / Kerberos, which is what Knowledge Manager expects. Use https wherever your installation offers it, and see TLS certificate validation for whether the connector checks the server's certificate.

Catalog shape and time

Parameter Type Required Description
HierarchyMode String No How the tag catalog is arranged into an asset tree. Default and recommended: "tagid". See Hierarchy modes
UserTimeZone String No Time zone applied when converting Knowledge Manager timestamps, e.g. "GMT+00:00". Set this to the zone your KM data is recorded in

Indexing

Parameter Type Required Description
Indexing.Frequency String Yes Full index interval. "1w" weekly, "1d" daily
Indexing.OnStartupAndConfigChange Boolean No Index immediately on agent start and after a config change. false is recommended for large catalogs, so a restart does not trigger a long run
Indexing.Next String Auto Next scheduled run — managed by the connector
VForge.Indexing.MaxIndexingDuration String No Ceiling on a single run, after which it stops cleanly rather than running indefinitely. Default "2h"
VForge.Indexing.IncrementalIndexingFrequency String — Not used by this connector. Leave null — ABB KM has no change feed

Frequency format: s seconds · m minutes · h hours · d days · w weeks · mo months

HTTP resilience

These govern how the connector behaves when Knowledge Manager is slow, throttling, or briefly unavailable. The defaults are sensible; change them when you know something specific about your server's capacity.

Parameter Type Description
VForge.Http.MaxRetries Integer Retry attempts for a failed request. Default 3
VForge.Http.BackoffBaseMs Integer Initial backoff before a retry, in ms. Default 200
VForge.Http.BackoffMaxMs Integer Ceiling on backoff growth, in ms. Default 20000
VForge.Http.RequestsPerSecond Integer Outbound rate limit. 0 means unlimited
VForge.Http.CircuitBreakerEnabled Boolean Stop hammering a failing endpoint and recover deliberately. Default true
VForge.Http.AdaptiveConcurrency Boolean Adjust in-flight request count to what the server is actually absorbing. Default true

Leaving the last two enabled is strongly recommended: together they turn an overloaded historian into visible, recoverable throttling rather than silent gaps in an index run.

TLS

Used only when WebServiceMethod is "https". See TLS certificate validation.

Parameter Type Description
VForge.Http.Tls.Trust String Which server certificates to accept: "Any" (default), "System" or "File". Not case-sensitive. A missing block or null means "Any"
VForge.Http.Tls.TrustStore String Path to a PEM or DER certificate file on the agent host. Used by "File" only

Monitoring and platform connectivity

Parameter Type Description
VForge.Monitoring.Enabled Boolean Publish the connector's own health and indexing activity into Seeq as a monitoring asset tree, trendable in Workbench. See Connectors ++
VForge.VirtualForgeEnabled Boolean Connector-level. The VirtualForge platform-connectivity switch, and disabled in the current release — the integration is architecture-present and runtime-off. See the optional VirtualForge connection

Security

Credentials

The connector signs in to Knowledge Manager as a service account. From this release that account's user name, password and domain are kept in the VForge secrets store on the Seeq agent host, not in the connector configuration, so they are not part of the configuration that Seeq administrators can view.

How it works

  • One file per agent host, vforge/secrets/credentials.json in the agent's data folder, shared by every Endeavor Engineering connector on that agent.
  • Each connection's credential is found by the connection's Id. Nothing is added to the configuration for this.
  • VFORGE_SECRETS means "use the store". The shipped template sets UserName, Password and Domain to it. When the store has no credential for a connection yet, the connector adds an empty entry for it, logs what to do, and leaves that connection inactive until the entry is filled in.
  • One account for many connections. If several Knowledge Manager servers use the same service account, store it once as a shared credential and point each connection at it.
  • Seeq's secrets-file references work too. A value such as SECRETS_FILE:keys/abbkm-km.key, in the configuration or in the store, is read from that file on the agent host, as Seeq's own connectors do.

Managing credentials with vf-agent

vf-agent is the command-line tool for the store, included with the connector. How to run it, set it up in PowerShell, Command Prompt or bash, and every command and option are on the vf-agent reference; step-by-step tasks with what you should see are on Using vf-agent. This section gives what is specific to the ABB Knowledge Manager connector.

For this connector Value
Product ID, in every secrets command seeq-connector-abbkm
A connection's ID The Id of the connection in the configuration
Configuration file configuration\link\ABB KM Connector V3.json in the agent's data folder
Credential fields that say "use the store" UserName, Password, Domain, each set to VFORGE_SECRETS
Credential type User name and password, with an optional Windows domain (NTLM or Kerberos)
Retire a connection Set "Enabled": false on it before removing its credential

Examples, with vfa set up as on the reference page:

vfa secrets verify --product seeq-connector-abbkm
vfa secrets set seeq-connector-abbkm <connection Id> --username svc-km --domain CORP
vfa secrets migrate --product seeq-connector-abbkm --all

Adding a connection. vf-agent adds it from this connector's own defaults, with no hand edit. Set the connection's server with --set (the settings are those of a connection in the configuration, such as WebServiceIP, WebServiceMethod, WebServicePort, HierarchyMode):

vfa datasources add seeq-connector-abbkm --name "KM Plant 2" --set WebServiceIP=km2.example.com --set WebServiceMethod=https --set WebServicePort=443 --apply --agent-stopped

It starts disabled, with VFORGE_SECRETS in UserName, Password and Domain, and prints the vf-agent secrets set line for its credential. Then datasources enable it. See Add a connection with vf-agent.

If you add a connection by hand instead, give it VFORGE_SECRETS in UserName, Password and Domain, as in the shipped template, and run vfa config check seeq-connector-abbkm before starting the agent. On its next start the connector adds an empty entry for it, keeps it inactive, and logs the command to run, with the connection's Id already in it:

Fill it with: vf-agent secrets set seeq-connector-abbkm <connection Id> --username USER --domain DOMAIN

Retiring a connection. To remove it and its signals and assets, archive its datasource in Seeq (Administration → Datasources → Archive, with its items). Seeq turns the connection off in ABB KM Connector V3.json straight away, and removes it at the agent's next start; then remove its credential with vfa secrets remove seeq-connector-abbkm --stale. Deleting the connection from the configuration instead leaves its items in Seeq. To stop it but keep it, disable it: vfa datasources disable seeq-connector-abbkm <connection Id> --apply --agent-stopped. See Retire a connection.

Replacing a connection. Seeq keeps its own copy of this configuration and matches it to the file by each connection's Id. Add the new connection, start the agent and check it connects, and only then disable or delete the old one; never replace the whole file. See Replace a connection.

Editing credentials.json by hand is possible, but not recommended. A formatting mistake, such as a missing comma or quote, makes the file unreadable: the connector keeps using the last copy it could read and logs an error, and connections that need a change wait until the file is fixed. A mistyped connection Id leaves that connection without a credential. vf-agent writes the file safely, even while the connector is running. If you do edit it, run vf-agent secrets verify afterwards.

Credentials in the configuration still work, for now. A connection whose configuration still holds its password keeps connecting: the connector uses the password, logs a warning that this is deprecated, and copies it into the store. vf-agent secrets migrate then replaces the configuration's values with VFORGE_SECRETS (with --apply, which asks before writing, and the Seeq agent stopped). Support for passwords in the configuration will be removed in a later release, announced in the release notes at least 30 days ahead.

Where the password exists, once moved

  1. The store file on the agent host. It is plain text, protected by file permissions. An administrator of the agent host can read it, the same boundary as Seeq's own secrets file. Limit it to the account that runs the Seeq agent and to administrators; on Linux the connector creates it readable by its owner only. vf-agent secrets verify reports wider access. If an account has access on purpose, such as a backup or monitoring account, name it with --allow-access <account> (repeatable): verify then accepts it and lists it in the result, so the record shows what was allowed.
  2. Nowhere else on the host. The connector's configuration backups (in vforge/config-backups/) never contain a password: values are replaced by ********. Backups written by earlier versions are masked the next time the connector starts.
  3. Not in Seeq. Seeq's view of the configuration (Administration, and the Seeq REST API) shows VFORGE_SECRETS. Check this after moving an installation.

Where it does not go. The connector uses the password only to authenticate to your Knowledge Manager server, over NTLM or Kerberos. Neither protocol sends the password itself over the network. The connector does not write the password to its logs or reports, and it makes no calls to Endeavor Engineering.

What we recommend

  • Use a dedicated service account with read-only access to the Knowledge Manager WebAPI, and no interactive sign-in. Do not use a person's account.
  • Move every connection to the store with vf-agent secrets migrate, and confirm with vf-agent secrets verify --require-store, which fails any connection whose password is still in the configuration.
  • Protect the agent data folder as you would the password. Limit it to the account that runs the Seeq agent and to administrators. On Linux, run vf-agent as that account.
  • Rotate the password on your normal schedule with vf-agent secrets set (or set-shared); it asks before replacing the old one (--yes in a script). The connector picks up the change the next time the connection connects.
  • Use https where your Knowledge Manager server offers it.

Where this is heading. If your organization needs more, tell us. Endeavor Engineering will add it in collaboration with you, matched to your environment and security policies. Options we already have in mind:

Option What it would do Notes
Integrated Windows authentication The Seeq agent runs as a domain service account, ideally a group Managed Service Account, and the connector authenticates as that account No password stored at all. Requires your Knowledge Manager server and Active Directory to accept the service account
Encrypted store The store's values are encrypted for the agent host, for example with Windows Data Protection Protects copies of the file. Does not protect against an administrator of the agent host
Operating-system credential store The store's entry names an entry in Windows Credential Manager Native on Windows agents; Linux agents would need an equivalent

TLS certificate validation

With WebServiceMethod: "https", the connection to Knowledge Manager is encrypted. Whether the connector also checks the server's certificate is set per connection by VForge.Http.Tls.Trust:

Trust Certificate check Hostname check When to use it
Any (default) None: any certificate is accepted None The behavior of every earlier release. Knowledge Manager servers often use self-signed certificates, so this stays the default, and upgrading changes nothing
System On a Windows agent: the Windows trust store and the Java trust store. On a Linux agent: the Java trust store Yes Your Knowledge Manager certificate is issued by a certificate authority your Windows machines already trust. Many sites distribute their internal CA this way
File Only the certificates in the file named by TrustStore Yes Your internal CA is not in the Windows trust store, the agent runs on Linux, or you want to pin one self-signed server certificate

The hostname check is always on for System and File. The name in WebServiceIP must match a name in the certificate. If WebServiceIP is an IP address, the certificate must list that address. Otherwise the connection is refused even though the certificate is otherwise trusted: a valid certificate for a different server proves nothing.

To pin a self-signed certificate: export the Knowledge Manager server's certificate (the public part only, as a .cer or .pem file), copy it to the agent host, and set:

"Tls": { "Trust": "File", "TrustStore": "C:\\ProgramData\\Seeq\\data\\keys\\km-server.pem" }

A certificate file holds no secret, but keep it where only administrators can replace it: whoever can swap the file decides which server the connector trusts. Pinning also means that when the server's certificate is renewed, you replace the file.

What you will see in the log. Once per connection at startup, a connection on https with Any logs a warning that certificate validation is off. A connection that validates logs which trust it uses. A setting the connector cannot honor, such as an unknown Trust value, File without a TrustStore, or a file it cannot read, is logged as an error, and that connection does not connect. It never falls back to accepting any certificate. Other connections are unaffected.

If validation fails against a server that should be trusted, the log names the reason: an untrusted certificate chain, or a certificate that does not match the host name.

Hierarchy modes

HierarchyMode decides how the flat Knowledge Manager tag catalog is arranged into a Seeq asset tree. All four modes produce the same item identities and the same signal names for a given tag — only the tree position differs.

Mode Shape
tagid Default and recommended. Organized by ABB TagId
kmlogs Organized by Knowledge Manager log structure
ptypes Organized by period type
flat No hierarchy — every signal at one level

Because identity does not change with the mode, switching modes re-shapes the tree without breaking existing worksheets that reference the signals in it. Changing mode does require a full index run to take effect.

What happens during an index run

Two phases, in order:

  1. Asset hierarchy, built sequentially from the Knowledge Manager tag catalog.
  2. Signals, created concurrently, arranged according to HierarchyMode.

Group Number and Channel Number are attached to each signal as properties, so they are searchable and filterable in Seeq alongside the signal itself.

Sample data is not moved during indexing. It is fetched from Knowledge Manager on demand when a user trends a signal, in bounded time chunks, with the connection's UserTimeZone applied.

Known behaviors

Worth knowing before they surprise you in an analysis:

  • Conditions are not produced. The connector implements Seeq's condition interface but returns no capsules. Conditions from Knowledge Manager are a planned enhancement, not part of the current feature set.
  • A null source value becomes a 0.0 sample rather than a gap. This is deliberate parity with the behavior of the connector's production predecessor, held pending customer confirmation rather than changed unilaterally — because silently reinterpreting historical data is worse than a documented quirk. If this matters to your analysis, tell us; it is tracked.
  • Malformed tags are skipped. A tag whose name does not parse to a well-formed identity — one containing a backslash, for instance — is left out rather than admitted with a broken identity.
  • Samples are ordered before they reach Seeq. Seeq rejects out-of-order samples, so the connector sorts ascending by timestamp first. This is what makes daylight-saving boundaries a non-event.

Troubleshooting

The connector does not appear in Seeq

Check that the ZIP was extracted into the agent's connector plugins directory and that the agent was restarted. The agent log states which connectors it loaded.

The datasource appears but nothing indexes

In order of likelihood:

  1. Enabled is still false — it ships that way.
  2. No valid license for this host. The log states the license state; without one the connector registers zero active datasources by design. See Licensing.
  3. WebServiceIP is still the placeholder, or the endpoint is unreachable from the agent host.
  4. No index run has happened yet. With OnStartupAndConfigChange set to false, the first run waits for the schedule. Trigger one from Seeq if you do not want to wait.

Authentication failures

Confirm the account, and whether it needs Domain set. NTLM authentication is connection-bound, so a misconfigured domain typically shows as consistent rejection rather than intermittent failure.

An https connection is refused after enabling certificate validation

The log line starting Cannot connect to ABB KM WebAPI server: gives the reason:

  • PKIX path building failed: the certificate is not trusted by the chosen Trust. With System, check that the issuing CA is in the agent host's trust store; with File, check that the file holds the CA (or the pinned server certificate) that actually signed it.
  • doesn't match any of the subject alternative names: the certificate is trusted but was issued for a different name. Set WebServiceIP to a name the certificate lists (often the fully qualified host name rather than a short name or IP address), or have the certificate reissued.

Setting Trust back to "Any" restores the previous behavior while you sort it out.

Indexing is slow, or does not finish

Large catalogs take time, and MaxIndexingDuration stops a run cleanly at its ceiling — a run that ends early is doing what it was told. If runs routinely hit the ceiling, either raise it or lengthen Frequency. If the historian is the bottleneck, leave AdaptiveConcurrency on and consider RequestsPerSecond to be a better citizen on a shared server.

Signals exist but return no data

Indexing and sample retrieval are separate operations against different Knowledge Manager calls, so a catalog can index while data pulls fail. Check UserTimeZone first — a wrong zone puts samples outside the window being trended — then the account's read access to tag data as distinct from the tag list.

Support

Include your Seeq version, the connector version, the connection's HierarchyMode, and the relevant agent log section. See Support for what EEI commits to and how to reach us — and note that however you raise an issue, with us or with Seeq, we work it through with Seeq support rather than handing it back to you.