Build

Connectors

Connectors bring operational data into the platform. They extract from source systems, normalize records, and map them into the ontology — turning raw tags and rows into typed, evidence-backed knowledge.

ForImplementation teamsDevelopersKnowledge engineers

Ingestion flow

Each connector follows the same path: extract from a source, normalize the payload, map it onto ontology types, and assert it into the graph with evidence attached. Change-data-capture, batch, and streaming modes share this pipeline.

Connector data flow

Source systems on the left; typed, grounded entities in the graph on the right.

Supported sources

Category	Examples	Typical mode
Control systems	OPC-UA, Modbus, SCADA	CDC / stream
Historians	PI, Aspen, Canary	Batch / stream
Enterprise	SAP, Oracle ERP, Maximo	CDC / batch
Manufacturing	MES, LIMS, QMS	CDC
Documents	PDFs, SOPs, P&IDs	Batch (extract + index)

Configuring a connector

Connectors are declared as versioned config. A mapping block ties each source field to an ontology type and attaches an evidence source, so provenance is captured at ingestion.

connectors/scada-plant04.yaml

# connectors/scada-plant04.yaml
source:
  type: opc-ua
  endpoint: opc.tcp://plant04.local:4840
  mode: cdc            # cdc | batch | stream
mapping:
  - from: "ns=2;s=Pump.1183.PV"
    to:   { entity: Asset, tag: "PUMP-1183", event: reading }
    evidence: { source: "scada:PLANT-04" }
schedule: "*/30 * * * * *"   # every 30s

Custom normalization

When a source needs logic beyond declarative mapping, attach a transform. Transforms run before facts reach the graph and must emit ontology-typed entities and events.

transforms/scada.ts

// Custom normalization runs before facts hit the graph.
export const normalize = defineTransform((raw) => ({
  entity: { type: "Asset", tag: raw.tagId.toUpperCase() },
  event: {
    kind: "reading",
    value: Number(raw.value),
    at: raw.timestamp,
  },
  evidence: [{ source: raw.channel, ref: raw.tagId }],
}))

Evidence is mandatory

A connector that emits facts without an evidence reference is rejected. Grounding at ingestion is what makes downstream reasoning defensible.

Operating connectors

1
Validate against the ontology
Dry-run mappings so type mismatches surface before data flows.
2
Backfill, then stream
Batch-load history first, then switch to CDC/stream for live updates.
3
Monitor freshness & lag
Alert on ingestion lag and dropped evidence to catch source outages early.