Migrating Canvas

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 Canvas configurations from asset-centric resource references to data modeling node references in Cognite Data Fusion (CDF).

Prerequisites

Before migrating Canvas, complete the following:

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 canvas:

Capability type	Action	Scope	Description
Data models	`datamodels:read`	`cdf_industrial_canvas`, `cdf_apps_shared`, `IndustrialCanvasInstanceSpace`	Scope `IndustrialCanvasInstanceSpace` to set up the Canvas tool.
Data model instances	`datamodelinstances:read`, `datamodelinstances:write`	`cdf_industrial_canvas`, `cdf_apps_shared`, `IndustrialCanvasInstanceSpace`, `SolutionTagsInstanceSpace`, `RuleInstanceSpace`	Scope `SolutionTagsInstanceSpace` to create, edit, and delete canvas labels. Scope `RuleInstanceSpace` to set up threshold rules.

The Cognite Toolkit reads each canvas, replaces asset-centric references with data modeling node references found through the InstanceSource view in the CogniteMigration data model, and creates a backup before uploading the updated configuration.

Run `cdf migrate canvas`

Run the command in interactive mode to select which canvases to migrate, or pass the options as arguments. See cdf migrate canvas --help.

cdf migrate canvas

Verify the migration

Open a migrated canvas and confirm that asset-centric references now point to data modeling nodes through their consumption views. The command also creates a backup under Version history in the Canvas UI.

How the migration works

The Cognite Toolkit reads the selected canvases and finds each reference to an asset-centric asset, time series, event, or file. For each reference, it looks up the corresponding data modeling node and consumption view in the InstanceSource view in the CogniteMigration data model, and replaces the reference. For example, a canvas with an asset and two event elements before migration:

Canvas showing asset-centric asset and event elements before migration in the Kelmarsh example.

After migration, the asset and events are replaced with data modeling nodes viewed through their consumption views. In the Kelmarsh example, the asset becomes a WindTurbine node and the events become StatusEvent nodes:

Canvas showing WindTurbine and StatusEvent data modeling nodes after migration in the Kelmarsh example.

What `cdf migrate canvas` does

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

Download the selected canvases

The Cognite Toolkit downloads the nodes and edges in the cdf_industrial_canvas:Canvas(version=v7) data model for each selected canvas.

Convert asset-centric references to data modeling node references

For each canvas, the Cognite Toolkit iterates through the ContainerReference view and finds all asset-centric references to assets, time series, events, and files. For each reference, it looks up the corresponding data modeling node and consumption view in the InstanceSource view in the CogniteMigration data model, then replaces the ContainerReference with a FdmInstanceContainerReference pointing to the data modeling node with the consumption view set as the view property.

Create a backup

Before uploading, the Cognite Toolkit creates a backup of the existing canvas configuration. The backup appears under Version history in the Canvas UI, so you can restore the canvas if anything goes wrong during migration. There is no automatic restore tool in the Cognite Toolkit itself.

Upload the migrated canvas configuration

The Cognite Toolkit updates the nodes and edges of each selected canvas in the cdf_industrial_canvas:Canvas data model with the migrated configuration.

Deploy

Migrating Canvas

Prerequisites

Required capabilities