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

> Step-by-step guide to migrate file annotations from an asset-centric 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 **file annotations** from an asset-centric Cognite Data Fusion (CDF) project to data modeling instances and recording lineage in the `CogniteMigration` data model.

## Prerequisites

Before migrating annotations, complete the following:

1. [Creating a data model and mappings](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/data_model_migration)
2. [Deploying the CogniteMigration data model](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/prepare)
3. [Migrating data sets](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/datasets)
4. [Migrating assets](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/assets)
5. [Migrating files and time series](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/files_timeseries)

<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 annotations`:

| Capability type      | Action                     | Scope                        | Description                                    |
| -------------------- | -------------------------- | ---------------------------- | ---------------------------------------------- |
| Files                | `files:read`               | The selected files data sets | From data set where you read the source files  |
| Annotations          | `annotations:read`         | All                          | Read all annotations                           |
| Data model instances | `datamodelinstances:write` | The selected instance space  | To space where you create the annotation nodes |
| Data model instances | `datamodelinstances:write` | cognite\_migration           | To create the lineage nodes                    |

## Migrating annotations

Only annotations of resource type `file` and annotation type `diagrams.AssetLink` or `diagrams.FileLink` can be migrated. See [Migrating 360 images](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/360_images) for 360° image annotation migration.

Select annotations by data set or CSV file, then run `cdf migrate annotations`.

<Steps>
  <Step title="Choose how to select annotations">
    Use [data set selection](#data-set-selection) to migrate all annotations linked to files in a data set. Use [CSV file selection](#csv-file-selection) to migrate a specific list of annotations.
  </Step>

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

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

  <Step title="Verify the migration">
    Confirm that annotation nodes exist in the target instance space for the selected files. See [Verify the migration](#verify-the-migration).
  </Step>
</Steps>

## Data set selection

To migrate all annotations linked to files in a data set, run the command in interactive mode:

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

The command prompts you to select the source data set (used to find the linked files and their annotations), and the target instance space where annotation nodes will be created. You can also pass all options as command-line arguments. See `cdf migrate annotations --help` for details.

## CSV file selection

To migrate annotations using a CSV file, run:

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
cdf migrate annotations --mapping-file <path to csv file>
```

Replace `<path to csv file>` with a path relative to your Cognite Toolkit project root.

This CSV file migrates an annotation from the Kelmarsh example:

```csv title="migration.annotations.csv" wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
space,externalId,id,ingestionView
source_data,newId,1245,cdf_asset_annotations_mapping
```

Required columns:

* `space`: The target instance space where the annotation will be created.
* `externalId`: The external ID of the resulting annotation.
* `id`: The integer **internal ID** of the source annotation to migrate. This ID is returned in the response of the [Filter annotations](/api-reference/concepts/20230101/annotations/filter-annotations) endpoint.

Optional columns:

* `ingestionView`: The resource view mapping to use. This is the annotation-specific equivalent of the `ingestionMapping` column used in other migration CSV formats. If omitted, the default mapping for annotations is used (typically the [CogniteDiagramAnnotation](/cdf/dm/dm_reference/dm_core_data_model#diagramannotation) view in the [CogniteCore model](/cdf/dm/dm_reference/dm_core_data_model)). Deploy custom mappings with `cdf build` and `cdf deploy` using the [Resource view mapping](/cdf/deploy/cdf_toolkit/references/resource_library#resource-view-mapping) resource type.

## Verify the migration

After a successful run, confirm that annotation nodes exist in the target instance space. Query the instance space in CDF or use the [DMS instances API](/api-reference/concepts/20230101/data-modeling/instances) to check that nodes with the expected `externalId` values are present.

For data set selections, compare the annotation node count in the target instance space against the number of source annotations returned by the [Filter annotations](/api-reference/concepts/20230101/annotations/filter-annotations) endpoint for the same data set.

## What `cdf migrate annotations` does

When you run `cdf migrate annotations`, the migration plugin performs the following steps on batches of annotations:

<Steps>
  <Step title="Download annotations">
    The Cognite Toolkit reads annotations from the asset-centric [annotations endpoint](/api-reference/concepts/20230101/annotations/filter-annotations), filtering for resource type `file` and annotation types `diagrams.AssetLink` and `diagrams.FileLink`.
  </Step>

  <Step title="Convert annotations to instance nodes">
    The Cognite Toolkit applies the mapping and converts each annotation to an instance node. The mapping is read from the `ingestionView` column in the CSV file, or the default mapping is used if no mapping is specified.
  </Step>

  <Step title="Write instance nodes to CDF">
    The Cognite Toolkit writes the created instance nodes to CDF using the `/models/instances` endpoint.
  </Step>

  <Step title="Create lineage nodes">
    While writing instances, the Cognite Toolkit creates lineage nodes in the `InstanceSource` view in the `CogniteMigration` data model to record the lineage from source annotations to the created instance nodes.
  </Step>
</Steps>

## Further reading

* [Migrating files and time series](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/files_timeseries)
* [Migrating 360 images](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/360_images)
* [Migrating Canvas](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/canvas)
* [Kelmarsh example](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/example)
* [Migration overview](/cdf/deploy/cdf_toolkit/guides/plugins/migration_plugin/steps)