> ## 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.

# Migrating Charts

> Step-by-step guide to migrate asset-centric Charts configurations to a data modeling-based Cognite Data Fusion (CDF) project.

<Warning>
  The migration plugin is an experimental feature. Updates to the Cognite Toolkit are likely to introduce changes to the described commands and processes.
</Warning>

This guide walks data engineers through migrating **Charts** configurations from asset-centric time series and event references to data modeling node references in Cognite Data Fusion (CDF).

## Prerequisites

Before migrating Charts, complete the following:

1. [Migrating files and time series](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/files_timeseries)
2. [Migrating events](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/events) (required only for charts that use event overlays)

<Note>
  If you have not completed some prerequisites, see [Manually populate the CogniteMigration data model](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/prepare#manual-population-of-the-cognitemigration-data-model).
</Note>

## Required capabilities

The following capabilities are required to run `cdf migrate charts`:

| Capability type | Action                                         | Scope | Description                                                                           |
| --------------- | ---------------------------------------------- | ----- | ------------------------------------------------------------------------------------- |
| ChartAdmin      | `chartsAdminAcl:read`, `chartsAdminAcl:update` | All   | Read and update all charts, including private and public charts owned by other users. |

## Migrating Charts

<Steps>
  <Step title="Test in a development project (recommended)">
    Copy Charts from production with the [data plugin](/cdf/deploy/cdf_toolkit/guides/plugins/data_plugin), then run the migration there first. See [Recommended procedure](#recommended-procedure).
  </Step>

  <Step title="Run `cdf migrate charts`">
    Run the command in interactive mode to select which Charts to migrate, or pass the options as arguments. See `cdf migrate charts --help`.

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf migrate charts
    ```
  </Step>

  <Step title="Verify the migration">
    Open a migrated chart and confirm that time series references use data modeling nodes, and that event overlays appear as specific activities.
  </Step>
</Steps>

## Recommended procedure

Run the migration in a development environment first using a copy of your production data. Use the [data plugin](/cdf/deploy/cdf_toolkit/guides/plugins/data_plugin) to copy Charts between environments.

To download Charts from the production environment:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf --env-path my_production_credentials.env data download charts
```

The command prompts you to select the charts you want to download.

To upload the downloaded Charts to the development or staging environment:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf --env-path my_dev_credentials.env data upload dir data/charts
```

All Charts uploaded to the development environment are owned by the service principal user you authenticated with.

## How the migration works

The Cognite Toolkit reads the selected charts and replaces asset-centric time series references with data modeling node references found through the `InstanceSource` view in the `CogniteMigration` data model. It also updates thresholds and calculations that reference asset-centric time series, and deletes call history for thresholds and calculations to avoid references to deleted time series.

For charts that use event overlays, the behavior differs between asset-centric and data modeling charts. In asset-centric charts, events are added dynamically based on a user-defined filter:

```yaml title="Asset-centric chart (event filter)" theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
eventFilters:
  - ...
    filters:
      dataSetIds:
      - id: 841335569281748
```

In data modeling charts, activities are added as specific node references. Replace `<my_instance_space>` with your target instance space:

```yaml title="Data modeling chart (activities collection)" theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
activitiesCollection:
  - isHighlighted: false
    isPinned: false
    nodeReference:
      space: <my_instance_space>
      externalId: Activity-1
    viewReference:
      space: cdf_cdm
      externalId: CogniteActivity
      version: v1
  - isHighlighted: false
    isPinned: false
    nodeReference:
      space: <my_instance_space>
      externalId: Activity-2
    viewReference:
      space: cdf_cdm
      externalId: CogniteActivity
      version: v1
```

When migrating event overlays, the Cognite Toolkit looks up all events matching the existing filter and the current date range of the chart, finds the corresponding activity nodes in `InstanceSource`, and adds them to the `activitiesCollection` section. After migration, the chart shows the same activities as before, but as specific node references instead of a dynamic filter.

## What `cdf migrate charts` does

When you run `cdf migrate charts`, the migration plugin performs the following steps:

<Steps>
  <Step title="Download the selected charts">
    The Cognite Toolkit downloads the chart frontend configuration along with monitoring jobs and scheduled calculations from the respective backend services.
  </Step>

  <Step title="Convert asset-centric chart to data modeling chart">
    The Cognite Toolkit replaces all asset-centric time series references with data modeling time series based on the `InstanceSource` view. This includes updating thresholds and calculations, and deleting call history to avoid stale references. For charts with event overlays, the tool looks up all matching events based on the event filter and current date range, and adds them as specific activities in the `activitiesCollection`.
  </Step>

  <Step title="Write the migrated chart configuration to CDF">
    The Cognite Toolkit updates the chart frontend configuration along with monitoring jobs and scheduled calculations in CDF with the migrated configuration.
  </Step>
</Steps>

## Further reading

* [Migrating Canvas](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/canvas)
* [Migrating files and time series](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/files_timeseries)
* [Testing migration of production data](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/test_data)
* [Kelmarsh example](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/example)
* [Migration overview](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/steps)