Migrating Charts

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

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:

Migrating files and time series
Migrating events (required only for charts that use event overlays)

If you have not completed some prerequisites, see Manually populate the CogniteMigration data model.

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.

Test in a development project (recommended)

Copy Charts from production with the data plugin, then run the migration there first. See Recommended procedure.

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.

cdf migrate charts

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.

Recommended procedure

Run the migration in a development environment first using a copy of your production data. Use the data plugin to copy Charts between environments. To download Charts from the production environment:

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:

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:

Asset-centric chart (event filter)

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:

Data modeling chart (activities collection)

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:

Download the selected charts

The Cognite Toolkit downloads the chart frontend configuration along with monitoring jobs and scheduled calculations from the respective backend services.

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.

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.

Deploy

Migrating Charts

Prerequisites

Required capabilities