> ## 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 from asset-centric to data modeling-based projects

> Follow the recommended sequence to migrate from asset-centric to data modeling-based Cognite Data Fusion (CDF) projects with the Cognite Toolkit.

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

Upgrading from asset-centric to data modeling-based Cognite Data Fusion (CDF) projects requires migrating data. The Cognite Toolkit provides a plugin, `cdf migrate`, that assists in this process.

The migration process is divided into a prerequisite phase, a preparation phase, and three distinct data migration phases. Each phase builds on the previous one, so complete them in order. You do not need to complete all phases — it depends on the requirements of your CDF project and which asset-centric resources and CDF features you currently use.

This guide gives you an overview of the steps to follow. Each step has a dedicated guide, and throughout, this guide uses a wind farm example introduced in the [Kelmarsh example](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/example).

## Prerequisites

### Use a development CDF project

Migration from asset-centric to data modeling is a significant change to your CDF project. Try the migration process in a development CDF project before running it in production. See [Testing migration of production data](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/test_data) for how to snapshot your production data and restore it in a development project.

### Data model and resource view mapping

Before starting, ensure the following are in place:

1. A target data model that extends the [CogniteCore model](/cdf/dm/dm_reference/dm_core_data_model). You can create this with [Neat](https://thisisneat.io/).
2. (Optional but strongly recommended) Mappings from your asset, event, time series, and file structures to the data model. These must be created manually.

For more information, see the [data modeling with mappings guide](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/data_model_migration).

## Preparation

### Deploy the CogniteMigration data model

The Cognite Toolkit tracks lineage from asset-centric to data modeling-based resources in a data model called `CogniteMigration`. This lineage is required for the application-level migration and access management phases. Deploy the data model by running:

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

For more information, see the [preparation guide](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/prepare).

### Instance spaces and source systems

Before starting asset-centric resource migrations, migrate data set resources and create `CogniteSourceSystem` nodes:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf migrate data-sets
```

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf migrate source-systems
```

These commands create instance spaces from the selected data sets and `CogniteSourceSystem` nodes from the `source` field on assets, events, and files. They also store lineage information in the `CogniteMigration` data model, which later migration phases require. Each command outputs the configuration for the created instance spaces and source systems to a `tmp/` directory. Move these files into a Cognite Toolkit module and govern them going forward.

For more information, see the [data sets migration guide](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/datasets) and the [source systems migration guide](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/source_systems).

## Asset-centric resource migrations

This phase migrates asset, event, time series, and file resources to instances (nodes) in data modeling. These resources underpin Canvas, Charts, annotations, InField, and 3D, so they must be migrated first. Migrate assets before all other resources, as assets are the anchor for all dependent resources.

### Migrate assets

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

For more information, see the [assets migration guide](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/assets).

### Migrate events

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

For more information, see the [events migration guide](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/events).

### Migrate files and time series

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf migrate files
cdf migrate timeseries
```

<Warning>
  The default behavior of `cdf migrate files` and `cdf migrate timeseries` is to link, not copy, resources. Linking locks the original resources, which can cause issues for your extractor — the original files or time series can no longer be modified or deleted. See the [files and time series migration guide](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/files_timeseries) for information about linking vs. copying and how to unlink resources if needed.
</Warning>

For more information, see the [files and time series migration guide](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/files_timeseries).

### Migrate annotations

Once assets and files have been migrated, migrate annotations:

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

For more information, see the [annotations migration guide](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/annotations).

### Migrating sequences

Sequences are not currently supported in the migration plugin.

## Application-level migrations

This phase migrates Canvas, Charts, InField, and 3D models.

### Migrate Canvas

<Note>
  Migrate annotations before Canvas. Canvas looks up annotations for display, and annotations migrated after Canvas will not appear.
</Note>

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

For more information, see the [Canvas migration guide](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/canvas).

### Migrate Charts

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

For more information, see the [Charts migration guide](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/charts).

### Migrate 3D models

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf migrate 3d
```

After the 3D model is migrated, migrate the 3D asset mappings:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf migrate 3d-mappings
```

For more information, see the [3D migration guide](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/3d).

### Migrate 360 images

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf migrate 360-images
```

After the 360 images are migrated, migrate the 360 image annotations:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf migrate 360-image-annotations
```

For more information, see the [360 images migration guide](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/360_images).

### Migrate InField

Get a template for new InField configurations:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf migrate infield-configs
```

Then migrate the InField data:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf migrate infield-data
```

If you use InField source data, you can also migrate it to CDM:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf migrate infield-source-data
```

For more information, see the [InField migration guide](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/infield).

### Migrate relationships

Relationships are not currently supported in the migration plugin.

## Access management migration

Update access groups to use data modeling instance spaces and the schema space instead of asset-centric data sets and resource types. This is currently a manual process.

## Manual tasks

After completing all migration phases, update the data ingestion and extraction processes to write data to the data modeling-based CDF project:

* Update extractors to write data to the correct instance spaces and data model concepts.
* Update transformations to write to your new data model instead of the asset-centric model.
* Update dashboards and visualizations to use the new data model concepts.

## Further reading

* [Kelmarsh example](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/example)
* [Known limitations](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/known_limitations)
* [Testing migration of production data](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/test_data)
* [Creating a data model and mappings](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/data_model_migration)