Skip to content

Metadata Connector — How It Works

The problem it solves

Industrial time-series data in Seeq is typically organized by raw tag names — identifiers like TI-101_PV or FIC-202_OUT that come directly from the control system. Meaningful on the historian, but difficult to navigate in Seeq: finding the right signal requires knowing the exact tag name.

Plant operations, however, are organized hierarchically. A process engineer thinks in terms of:

Site → Area → Unit → Equipment → Measurement

The VirtualForge Metadata Connector bridges this gap. It reads your existing asset-hierarchy metadata from an external metadata source and automatically builds a matching structure inside Seeq. Engineers browse assets the way they think about the plant, not the way the historian stored the data.

Beyond navigation, a structured asset tree carries context. Metadata typically holds more than hierarchy — equipment identifiers, process area codes, product classifications — and the connector attaches these as properties on the assets and items it creates, so they are searchable and filterable across the tree and traceable back to the source system.

A better approach: connector-based metadata indexing

Formula-based linking

The conventional approach to organizing Seeq data copies signals into the target hierarchy. This creates two problems:

  • Storage overhead — every copied signal doubles the data footprint
  • Drift — copied data can fall out of sync with the authoritative source

The VirtualForge Metadata Connector takes a different path. Instead of copying, it creates Seeq formula items that dynamically reference the original tags by name. Formulas resolve at query time — always reading live data from the source, never from a copy.

Metadata source says:
  "Temperature_123" belongs to  PlantA → Area1 → Tank5

Connector creates in Seeq:
  PlantA (Asset)
    └─ Area1 (Asset)
        └─ Tank5 (Asset)
            └─ Temperature (Formula → references "Temperature_123" live)

Result: Engineers navigate a clean plant hierarchy. Every signal reflects live, authoritative data. No duplication. No drift. No storage penalty.

Why a dedicated connector for metadata

Seeq already has a supported SQL connector, and it is very good at what it does: given a database of time-series data, it serves that data into Seeq as signals. What it does not do is build an asset tree. It can tell Seeq that a signal exists; it cannot tell Seeq that the signal belongs to Tank 5, inside Area 1, at Plant A — or carry the equipment identifiers and process codes that make the signal findable.

That is the gap this connector fills. Where the SQL connector has served the data, this connector supplies the hierarchy, the properties, and the formula links binding the two together — so the signals arrive in context rather than as a flat list. Where both read the same ForgeVault database, that shared source is what keeps them consistent with each other.

Why a connector instead of a script

The traditional alternative to a dedicated connector is a Python script run in Seeq Data Lab. Scripts can build asset trees, but they require ongoing maintenance to handle:

  • Periodic execution — scheduling reruns as metadata evolves
  • Deduplication — avoiding recreating assets that already exist
  • Cleanup — archiving assets for metadata records that have been removed
  • Error handling and logging — diagnosing failures across large datasets

The Seeq Connector SDK is purpose-built for exactly this workload. By implementing metadata indexing as a connector, all of this is handled out of the box — scheduled full and incremental indexing, safe repeat runs, automatic cleanup, and structured logging. Endeavor Engineering adds further enhancements on top of the SDK: enhanced logging, upgrade tooling, and ongoing compatibility maintenance as Seeq evolves.

How the connector works

Step 1 — read the metadata

The connector connects to each configured metadata source and retrieves its asset-to-item records. Each record describes where a signal belongs in the plant hierarchy, which source item it corresponds to, and any properties to carry into Seeq.

There are two routes by which metadata reaches the connector, and which one fits depends on the source system rather than on a preference of ours:

Route How it works
Direct to the source system The connector connects to the source and reads its metadata at index time. The metadata-source interface exists for exactly this, so no intermediate store is involved
Via ForgeVault The source delivers into ForgeVault — EEI's portable metadata and operational data store — and the connector reads it there

Direct is the simpler shape where the source allows it. A system that can be queried for its metadata, and that is reachable from the Seeq agent, needs nothing in between.

ForgeVault is the answer where direct is not available — and it earns its place more often than you might expect. A source that only emits extracts on a schedule, one that cannot be reached from the agent host, one whose metadata needs normalizing or combining with another system's before it is usable, or one you would rather not have a connector querying in production: in all of those, landing the content in ForgeVault first is what makes the rest work. It also lets the same store serve Seeq's SQL connector with the data while this connector supplies the hierarchy.

Status, plainly. ForgeVault is the metadata source the connector ships with today, so a deployment using it is the well-trodden path. A direct connection is what the interface is designed for, and each one is specified and built as engagement scope — the connector itself is unchanged either way.

A worked example of the ForgeVault route: SAP Quality Management, Available through an EEI engagement. SAP QM's own CSV extract is passed straight into a ForgeVault stored procedure, which lands it as data and metadata tables. Built for and proven in a production SAP QM deployment. SAP integrations are specific by nature, and that one is no exception — a defined path for that source rather than a generic SAP adapter.

If you have a system you would like connected, we would like to hear about it: tell your Endeavor Engineering contact, or reach us through the resources hub.

Separately, the connector can resolve a signal's Seeq identity by searching your Seeq server when the metadata names an item without recording its Seeq id. That lookup can run against the Seeq server the connector is already attached to, or another one.

Step 2 — build the asset tree

The connector constructs the full asset hierarchy in Seeq — creating every level from site down to equipment, and attaching the asset properties defined in the metadata. Parent assets are created first so the tree assembles in the correct order. Assets that already exist are reused rather than recreated, making repeat runs safe and efficient.

Step 3 — create the formula items

For each leaf asset, the connector creates a Seeq formula item that references the existing item the metadata points at. The reference is type-aware, so this is not limited to plain signals:

  • A referenced signal yields a formula signal returning the source signal's samples.
  • A referenced condition yields a formula condition returning the source condition's capsules and their properties — so a limit or event condition that already exists in Seeq can be placed into the new hierarchy.
  • A referenced scalar yields the scalar's value.
  • Properties are attached to the assets and items the connector creates — equipment identifiers, process area codes, product classifications and other attributes carried in the metadata record — making items searchable and filterable across the tree.

In every case the connector is placing and referencing items, never recomputing them: the source item stays authoritative, and its type and behavior are inherited rather than restated.

If a source item's Seeq id is not already recorded in the metadata, the connector resolves it automatically and caches the result for future runs. Formula creation runs in parallel across assets, keeping indexing fast on large datasets.

Planned: deriving new calculated items — specification limits, operating envelopes, process boundaries — from expressions held in the metadata. Committed direction rather than work you can use today; details and availability may change. In the current release those items must already exist in Seeq for the connector to place them.

Step 4 — stay current

The connector runs on two schedules simultaneously:

  • Full index — rebuilds the complete asset tree on a configurable interval (weekly or monthly for stable datasets). Handles additions, removals, and structural changes.
  • Incremental index — checks for metadata changes at a much shorter interval (as low as one minute). Only processes records flagged as updated, minimizing Seeq API calls and delivering near real-time visibility of metadata changes in Seeq.

Organizational flexibility

Single-source layout

When a single metadata source drives the entire hierarchy, the connector creates Seeq roots directly from the metadata:

[Metadata Root A] → Seeq root asset
[Metadata Root B] → Seeq root asset

Multi-source RootSet layout

When multiple sources contribute to the same Seeq deployment, a RootSet groups each source's assets under a named container:

SAP QM (RootSet)
  └─ PlantA (metadata root)
       └─ Area1 → Tank5 → Temperature

MES System (RootSet)
  └─ Line1 (metadata root)
       └─ Station2 → Conveyor → Speed

Each source's assets remain clearly separated in the Seeq tree, with no naming conflicts between sources.

What this means for your team

Role Before After
Process engineer Searches by raw tag id; must know the exact naming convention Browses plant hierarchy → unit → measurement, with asset context already in place
Analytics / data science Hunts for the right tags and rebuilds asset context for each analysis Signals, conditions, and properties are already organized and labeled across the tree; start from the asset, not the tag list
IT / OT Team Manually maintains Seeq asset trees when metadata changes; scripts need scheduling and cleanup logic Updates the metadata source; the connector detects changes incrementally and syncs Seeq in near real-time
Seeq Administrator Builds asset trees by hand or maintains Data Lab scripts that require ongoing upkeep Deploys the connector once; scheduled indexing, deduplication, cleanup, and logging are all handled automatically

Key technical properties

  • Complements Seeq's SQL connector — supplies the asset tree and properties the SQL connector cannot, over the same database
  • No data duplication — formula items reference source data live; nothing is copied
  • Type-aware references — signals, conditions, and scalars are all placed into the hierarchy, inheriting the source item's behavior
  • Metadata-driven context — properties come from the metadata record, not from hardcoded mappings
  • Near real-time incremental sync — metadata changes can appear in Seeq within minutes
  • Connector SDK foundation — scheduling, deduplication, cleanup, and structured logging are handled at the platform level
  • Extensible source architecture — new metadata sources can be added without modifying the core connector
  • Multi-source — any number of metadata sources can be active simultaneously in a single deployment
  • State-aware — when organizational configuration changes, the connector detects the transition and archives the old structure cleanly

Learn more