> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Extracting state time series with the OPC UA extractor

> Enable opt-in state time series ingestion from OPC UA multi-state and enumeration variables in data modeling projects.

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](/dev/concepts/resource_types/state_timeseries) in data modeling projects. Charts and analysis tools can plot the numeric state code while labels stay readable in tooltips and legends.

<Note>
  This feature is in [public preview](/cdf/product_feature_status#public-preview) and may change.
</Note>

## Before you start

* Use **Cognite OPC UA extractor 3.0.0** or later.
* Set up the extractor through [Integrations](/cdf/integration/guides/interfaces/about_unified_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](/cdf/access/guides/capabilities#opc-ua-extractor).
* Complete [Set up the OPC UA extractor](/cdf/integration/guides/extraction/opc_ua/opc_ua_setup) with a working connection to your OPC UA server.

## What the extractor creates

When [`extraction.data-types.states.enabled`](/cdf/integration/guides/extraction/opc_ua/opcua#extraction.data-types.states) 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`](/cdf/integration/guides/extraction/opc_ua/opcua#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`](/cdf/integration/guides/extraction/opc_ua/opcua#extraction.data-types.states). This avoids duplicate series for the same variable. Whether you migrate is optional and depends on your downstream consumers.

## Enable state time series extraction

<Steps>
  <Step title="Enable state time series in the configuration file">
    Edit `config.yml` and set `extraction.data-types.states.enabled` to `true` under the [`data-types`](/cdf/integration/guides/extraction/opc_ua/opcua#extraction.data-types) section. Set `extraction.data-types.auto-identify-types` to `true` when you ingest enumeration variables.

    ```yaml theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    extraction:
      data-types:
        auto-identify-types: true
        states:
          enabled: true
    ```

    See the [`states` configuration reference](/cdf/integration/guides/extraction/opc_ua/opcua#extraction.data-types.states) for parameter descriptions.
  </Step>

  <Step title="Restart the extractor">
    Restart the extractor as described in [Start the extractor](/cdf/integration/guides/extraction/opc_ua/opc_ua_setup#start-the-extractor) so it rebrowses the OPC UA node tree and applies the new settings.
  </Step>

  <Step title="Verify state sets and data points in CDF">
    Use the [data modeling API](/dev/concepts/resource_types/state_timeseries) 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**.
  </Step>
</Steps>

## 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](/cdf/integration/guides/extraction/opc_ua/opc_ua_troubleshooting).