Metadata Connector — User Guide¶

Overview¶

The VirtualForge Metadata Connector is a Seeq connector built by Endeavor Engineering that reads asset-hierarchy metadata from one or more external metadata sources and publishes it as a live, structured asset tree inside Seeq — without duplicating your signal data. In EEI's terms it is a metadatasource rather than a datasource: it contributes metadata about signals that already exist, not data of its own.

The core idea is metadata separation: the asset hierarchy you see in Seeq is driven by your metadata, not by the structure of your historian or control system. When your operational model changes — new equipment, a reorganized facility, a different way of grouping assets — you update the metadata. The signals never change. Seeq reflects the new context automatically.

Fermentation Building → Seed Train Suite → Seed Fermenter SF-101 → Agitator Speed
  (Metadata defines this)                                            (Signal unchanged)

Key capabilities: - Reads metadata from one or more configured metadata sources - Constructs the full asset hierarchy in Seeq — every level, from site down to measurement - Creates Seeq formula items that reference existing source items live — no data copy, no drift - References items by type — a referenced signal returns samples, a referenced condition returns capsules, a referenced scalar returns its value — so existing limit and event conditions can be placed into the new hierarchy - Attaches properties to assets and formula items, making them searchable and filterable in Seeq - Runs scheduled full indexing and frequent incremental indexing for near real-time metadata updates - Supports multiple metadata sources simultaneously, each with its own RootSet grouping

What is a metadata source?¶

A metadata source is any system that holds the metadata describing how your assets are organized — which signals belong where, what they represent, and how the hierarchy is structured. This connector reads from a metadata source rather than from a raw signal source, which is what distinguishes it from a conventional Seeq connector.

The connector can reach a metadata source two ways, and How It Works covers the choice in full:

Directly, where the source system can be queried for its metadata at index time and is reachable from the Seeq agent. No intermediate store is involved.
Via ForgeVault, where direct access is not available or not wanted — the source delivers into ForgeVault and the connector reads it there.

ForgeVault is the metadata source the connector ships with today, and the configuration below is written against it. A direct connection is what the metadata-source interface is designed for, and each one is specified and built as engagement scope; the connector configuration is unchanged either way.

For the ForgeVault route, the source delivers into ForgeVault rather than talking to Seeq directly:

Source system	How it reaches ForgeVault
SAP Quality Management	Available through an EEI engagement. SAP QM's CSV extract is passed into a ForgeVault stored procedure, which lands it as data and metadata tables. Built for and proven in a production SAP QM deployment
Other systems — a CMMS, an ERP, a historian export, a custom metadata database	Specified and built as engagement scope. The connector configuration is unchanged either way

Because ingestion is handled at the database, adding a source that route does not change anything running inside Seeq. If you have a system you would like connected, we want to hear from you — reach out to your Endeavor Engineering representative or contact us through the resources hub.

ForgeVault¶

ForgeVault is Endeavor Engineering's purpose-built metadata and operational data store. It provides a portable, integration-native repository for asset hierarchy metadata, signal registries, and time-series data — designed to sit between your source systems and Seeq so that your operational model is managed independently of your historian or control system.

In a typical deployment ForgeVault is read by two connectors: Seeq's supported SQL connector serves the time-series data, and this connector supplies the asset tree, the properties, and the formula links that attach those signals to their place in the hierarchy. Seeq's SQL connector does not build an asset tree, which is the reason this connector exists.

ForgeVault is provisioned and managed by Endeavor Engineering. The VirtualForge Metadata Connector connects to it using the credentials and connection parameters provided in your deployment configuration. The schema, data isolation, and access controls are handled at the ForgeVault level — you do not manage the database directly.

Key fields the connector reads from ForgeVault per signal record:

Field	Purpose
Signal name and description	Display name and label for the formula item in Seeq
Asset path	Hierarchical location (`Building / Suite / Equipment`)
Root asset	Top-level grouping within a metadata source
Seeq item reference	The source tag the formula item will reference
Update flag	Whether this record has changed since the last incremental index

Seeq item resolution¶

A DatasourceType of "SEEQ" is not a metadata source — it supplies the credentials the connector uses to find a Seeq item when the metadata names one without recording its Seeq id. The connector searches for the item, then caches the id so later index runs skip the lookup.

That search can run against the Seeq server the connector is already attached to (the usual case, requiring no URL or credentials) or against a different Seeq server. The asset structure itself always comes from a metadata source.

A Real-World Example¶

A nutraceutical manufacturer uses multiple sensor networks across three buildings: a Controlled Environment Building with cultivation halls, a Fermentation Building with seed train and production bioreactors, and a Post-Processing Building with drying rooms and cold storage.

The raw signals in their historian are named by instrument tag: TI-101_PV, AI-202_OUT, FIC-301_OUT. These are accurate but opaque — no one outside the controls team knows what they mean without a map.

With ForgeVault as the metadata source:

The signal registry in ForgeVault records that TI-101_PV belongs to Fermentation Building → Seed Train Suite → Seed Fermenter SF-101 → Broth Temperature
The connector reads that metadata and builds the asset hierarchy in Seeq
Process engineers browse by plant area and find Broth Temperature under SF-101 — without needing to know the tag name

Seeq Asset Tree (connector-built):
  Fermentation Building
    └─ Seed Train Suite
        └─ Seed Fermenter SF-101
            ├─ Broth Temperature          (Formula → TI-101_PV, live)
            ├─ Agitator Speed             (Formula → AI-202_OUT, live)
            ├─ Dissolved Oxygen           (Formula → FIC-301_OUT, live)
            ├─ Broth Temperature — Hi     (Formula condition → existing Seeq limit condition)
            ├─ Broth Temperature — Lo     (Formula condition → existing Seeq limit condition)
            └─ [Properties: Equipment ID, Process Area, Product Code, ...]

Because references are type-aware, the tree is not limited to plain signals: where a limit or event condition already exists in Seeq, the metadata can place it on the asset alongside the measurements, and it arrives as a first-class Seeq condition ready for capsule analysis.

Properties are attached to assets and formula items directly from the metadata record — equipment identifiers, process area codes, product classifications, and any other attributes your metadata source carries. Properties make assets searchable and filterable across the entire asset tree, and provide the traceability link back to the source system.

When the facility adds a new fermenter, the metadata record is added to ForgeVault. On the next incremental index cycle — running as frequently as every minute — the new asset, its signals, and its properties appear in Seeq automatically.

Planned: generating new calculated items from expressions held in the metadata — limits and envelopes computed by the connector rather than referenced. Committed direction rather than work you can use today; details and availability may change.

Installation¶

Prerequisites¶

A Seeq Server with a Seeq Link remote agent
Java 21+ on the remote agent host
A provisioned ForgeVault instance — provided by Endeavor Engineering
A license file issued for the agent host (see Licensing below)

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

Deployment Steps¶

Obtain the connector ZIP from your Endeavor Engineering contact.
Deploy to the Remote Agent:
Copy the ZIP to the Remote Agent machine
Extract to the agent's connector plugins directory, or use Seeq Admin → Remote Agents → Upload Connector
Create the configuration file at <agent data folder>/configuration/link/VForge Meta Connector.json (see Configuration File Structure below).
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 at the path named in the agent log.
Restart the Remote Agent.
Verify:
The agent log shows the connector loading, and a license line reading state=LICENSED
In Seeq, under Administration → Datasources — the datasource appears
After the first index run, the asset tree and its items appear

Licensing¶

The connector is licensed per host. Until a license issued for that host is installed it starts normally, logs its status, and indexes nothing — so an empty asset tree on a healthy-looking agent is the expected appearance of a missing license rather than a fault. The agent log always states the current license state, and the license is never stored in the configuration file, so a Seeq configuration reset cannot remove it.

Configuration File Structure¶

The connector is configured via VForge Meta Connector.json.

A note on the names you will see in the file. VForge Meta Connector.json, the VForge Meta Connection default connection name, and the VForge ID property are the connector's on-disk identifiers — the literal strings Seeq and the connector use. They are not the product name, and renaming them would break an existing configuration, so they stay as they are.

{
  "Version": "com.vforge.seeq.link.connector.config.VForgeMetaConnectorConfigV1",
  "Connections": [
    {
      "Name": "VForge Meta Connection",
      "Id": "75f86357-8b1a-4fbb-b900-d04e481cb898",
      "Enabled": true,

      "Indexing": {
        "Frequency": "1w",
        "OnStartupAndConfigChange": false,
        "Next": "2026-03-20T19:34:35.326Z"
      },

      "VForge": {
        "Indexing": { "IncrementalIndexingFrequency": "1m" }
      },

      "MetadataDatasources": [
        {
          "DatasourceType": "ForgeVault",
          "Name": "SAP QM Metadata",
          "RootSet": "SAP Quality Management",
          "Enabled": true,
          "MaxConcurrentTasks": 8,

          "Host": "db.example.com",
          "Port": 5432,
          "Database": "sap_qm",
          "Schema": "public",
          "Username": "readonly_user",
          "Password": "secure_password",
          "MetadataTable": "signal_metadata"
        }
      ]
    }
  ]
}

Configuration Parameters¶

Connection-Level Parameters¶

Parameter	Type	Required	Description	Example
`Name`	String	Yes	Display name for the connection	`"VForge Meta Connection"`
`Id`	String	Yes	Unique identifier (keep generated value)	`"75f86357-..."`
`Enabled`	Boolean	Yes	Enable or disable this connection	`true`

Indexing Parameters¶

Parameter	Type	Required	Description	Example
`Frequency`	String	Yes	Full index interval	`"1w"` (weekly), `"1d"` (daily)
`OnStartupAndConfigChange`	Boolean	No	Auto-index on agent startup?	`false` (recommended for large datasets)
`Next`	String	Auto	Next scheduled index time (auto-managed)	`"2026-03-20T19:34:35Z"`
`VForge.Indexing.IncrementalIndexingFrequency`	String	No	How often to check for incremental updates. Omit to disable	`"1m"`, `"5m"`
`CleanupDryRun`	Boolean	No	Log cleanup actions without executing them	`true` (default: `false`)
`CleanupAnchorLayer`	Integer	No	Path depth for incremental cleanup (1 = Layer 2)	`1` (default: `1`)

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

Metadata source parameters¶

Parameter	Type	Required	Description	Example
`DatasourceType`	String	Yes	`"ForgeVault"` for a metadata source; `"SEEQ"` for a Seeq item-resolution entry	`"ForgeVault"`
`Name`	String	Yes	Display name for this metadata source	`"SAP QM Metadata"`
`RootSet`	String	No	Top-level grouping asset name	`"SAP Quality Management"`
`Enabled`	Boolean	Yes	Enable or disable this metadata source	`true`
`MaxConcurrentTasks`	Integer	No	Parallel threads for formula creation	`8` (default: 4)
`PropertiesToTransfer`	Array	No	Metadatasource item properties to copy to formula items	`["Asset Path", "VForge ID"]`

Common Setup Scenarios¶

Scenario 1: a single ForgeVault metadata source¶

A single ForgeVault instance drives the entire asset hierarchy. With RootSet: null, metadata roots become Seeq roots directly — the plant structure defined in ForgeVault maps one-to-one into the Seeq asset tree.

{
  "MetadataDatasources": [
    {
      "DatasourceType": "ForgeVault",
      "Name": "Plant Operations",
      "RootSet": null,
      "Enabled": true,
      "Host": "forgevault.example.com",
      "Port": 5432,
      "Database": "vf_plantops",
      "Schema": "vf_data",
      "Username": "vf_plantops_reader",
      "Password": "...",
      "MetadataTable": "signal_metadata",
      "MaxConcurrentTasks": 8
    }
  ],
  "Indexing": {
    "Frequency": "1w",
    "OnStartupAndConfigChange": false
  },
  "VForge": {
    "Indexing": { "IncrementalIndexingFrequency": "1m" }
  }
}

Scenario 2: multiple metadata sources with RootSet grouping¶

Two or more metadata sources contribute to the same Seeq deployment. Each gets a RootSet name that becomes its top-level container in the Seeq asset tree, keeping each source's assets clearly separated with no naming conflicts.

{
  "MetadataDatasources": [
    {
      "DatasourceType": "ForgeVault",
      "Name": "SAP QM",
      "RootSet": "Quality Management",
      "Enabled": true,
      "Host": "forgevault.example.com",
      "Database": "vf_sapqm"
    },
    {
      "DatasourceType": "ForgeVault",
      "Name": "MES System",
      "RootSet": "Manufacturing Execution",
      "Enabled": true,
      "Host": "forgevault.example.com",
      "Database": "vf_mes"
    }
  ]
}

Result:

Seeq Asset Tree:
  Quality Management      ← RootSet for SAP QM
    └─ [asset tree from SAP QM metadata]
  Manufacturing Execution ← RootSet for MES
    └─ [asset tree from MES metadata]

Scenario 3: incremental indexing for near real-time updates¶

The incremental index polls for changed records at a short interval and processes only the affected branches. The full index runs weekly to handle structural changes, additions, and removals.

{
  "Indexing": {
    "Frequency": "1w",
    "OnStartupAndConfigChange": false
  },
  "VForge": {
    "Indexing": { "IncrementalIndexingFrequency": "1m" }
  },
  "CleanupDryRun": false,
  "CleanupAnchorLayer": 1
}

With IncrementalIndexingFrequency: "1m", a metadata update in ForgeVault will appear in Seeq within approximately one minute.

Troubleshooting¶

Connector not appearing in Seeq¶

Check the remote agent log for connector load errors
Verify Java 21+ is installed: java -version
Confirm the ZIP was extracted correctly

Empty asset tree¶

Check the license line in the agent log first. An unlicensed connector indexes nothing, and this is the most common cause of an empty tree on an otherwise healthy agent.

Then:

Verify connectivity to the metadata source (host, port, credentials)
For incremental mode: check that has_data_updates is not all false

Check agent logs for:

Processing metadata from datasource: {Name}
Metadata processing complete: X total, Y errors

Formula items not created¶