Skip to main content
The Cognite OPC UA extractor can ingest both the numeric value and string label from OPC UA state variables into a single plottable state time series in data modeling projects. Charts and analysis tools can plot the numeric state code while labels stay readable in tooltips and legends.
This feature is in public preview and may change.

​
Before you start

  • Use Cognite OPC UA extractor 3.0.0 or later.
  • Set up the extractor through Integrations (public preview). State time series ingestion is available for OPC UA extractors registered as on-premises integrations.
  • Configure the extractor to write to a data modeling project, not asset-centric data only.
  • Assign data model instances capabilities (datamodelinstances:read and datamodelinstances:write) for the target space. See Capabilities for the OPC UA extractor.
  • Complete Set up the OPC UA extractor with a working connection to your OPC UA server.

​
What the extractor creates

When extraction.data-types.states.enabled is true, the extractor:
  1. Creates state sets (CogniteStateSet) for supported OPC UA variables.
  2. Creates state time series with type: "state" and links each series to its state set.
  3. Writes state data points with a numeric state code and a human-readable label on each change.
The feature is opt-in; the config defaults to false, so existing extractor behavior is unchanged until you enable it.

​
Supported OPC UA state variables

The extractor chooses multi-state, enumeration, or two-state discrete handling automatically during browse.
  • Multi-state: States are defined on the variable (one tag, one state list). OPC UA types include MultiStateDiscreteType and MultiStateValueDiscreteType.
  • Enumeration: States are defined on a shared type (many tags, one state list). Set extraction.data-types.auto-identify-types to true. The extractor reads state definitions from DataTypeDefinition when available (OPC UA 1.05) and uses EnumStrings or EnumValues only when DataTypeDefinition does not define them.
  • Two-state discrete: Boolean variables with two states defined on the server (for example active and inactive). OPC UA type is TwoStateDiscreteType.

​
Existing time series

Enabling state time series ingestion does not convert or delete existing time series. The extractor does not delete time series or data points. If a variable already has a string or numeric time series in CDF, the extractor skips creating a state time series for that variable. Search extractor logs for skipping creation of state timeseries. If you previously ingested the variable as a string time series and want state time series instead, delete the existing time series and reingest after you enable extraction.data-types.states.enabled. This avoids duplicate series for the same variable. Whether you migrate is optional and depends on your downstream consumers.

​
Enable state time series extraction

1

Enable state time series in the configuration file

Edit config.yml and set extraction.data-types.states.enabled to true under the data-types section. Set extraction.data-types.auto-identify-types to true when you ingest enumeration variables.
See the states configuration reference for parameter descriptions.
2

Restart the extractor

Restart the extractor as described in Start the extractor so it rebrowses the OPC UA node tree and applies the new settings.
3

Verify state sets and data points in CDF

Use the data modeling API to confirm that ingestion succeeded:
  1. CogniteStateSet instances exist in CDF: one per multi-state variable, or one shared set per enumeration type.
  2. Affected time series have type: "state" and link to a state set.
  3. Recent data points include a numeric state code and a human-readable label.

​
Limitations

  • Data modeling projects only — State time series extraction does not apply when writing only to asset-centric data.
  • Opt-in — Disabled by default; enable extraction.data-types.states.enabled explicitly.
  • 100-state limit (platform) — CDF state sets support at most 100 states. If an OPC UA variable defines more than 100 states at browse, the extractor does not create a state set or state time series and ingests the variable as a regular time series instead. If a state set later grows past 100 states, the extractor logs an error and stops updating that time series.
  • State set updates — Changes to state definitions on the OPC UA server are picked up on rebrowse only, not during live subscription. Until CDF reflects the updated state set, state codes outside the current CDF state set are written with status BadOutOfRange and have no value.
  • Errors in logs — Limit violations and invalid state values are logged by the extractor; they are not surfaced in the CDF UI. See Troubleshoot the OPC UA extractor.
Last modified on September 9, 2026