cognite-toolkit 0.6.39__py3-none-any.whl → 0.7.30__py3-none-any.whl

cognite_toolkit/_cdf_tk/commands/_migrate/data_classes.py

@@ -1,20 +1,34 @@
+from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Literal
+from typing import Annotated, Any, Generic, Literal
 
-from cognite.client.data_classes.data_modeling import NodeId, ViewId
+from cognite.client.data_classes._base import (
+    WriteableCogniteResource,
+    WriteableCogniteResourceList,
+)
+from cognite.client.data_classes.data_modeling import EdgeId, InstanceApply, NodeId, ViewId
+from cognite.client.utils._identifier import InstanceId
 from cognite.client.utils._text import to_camel_case
-from pydantic import BaseModel, field_validator, model_validator
+from pydantic import BaseModel, BeforeValidator, field_validator, model_validator
 
+from cognite_toolkit._cdf_tk.client.data_classes.instances import InstanceApplyList
 from cognite_toolkit._cdf_tk.client.data_classes.migration import AssetCentricId
 from cognite_toolkit._cdf_tk.client.data_classes.pending_instances_ids import PendingInstanceId
-from cognite_toolkit._cdf_tk.commands._migrate.default_mappings import create_default_mappings
-from cognite_toolkit._cdf_tk.exceptions import (
-    ToolkitValueError,
+from cognite_toolkit._cdf_tk.commands._migrate.default_mappings import (
+    ASSET_ANNOTATIONS_ID,
+    FILE_ANNOTATIONS_ID,
+    create_default_mappings,
 )
+from cognite_toolkit._cdf_tk.exceptions import ToolkitValueError
 from cognite_toolkit._cdf_tk.storageio._data_classes import ModelList
+from cognite_toolkit._cdf_tk.utils.useful_types import (
+    AssetCentricKindExtended,
+    JsonVal,
+    T_AssetCentricResourceExtended,
+)
 
 
-class MigrationMapping(BaseModel, alias_generator=to_camel_case, extra="ignore"):
+class MigrationMapping(BaseModel, alias_generator=to_camel_case, extra="ignore", populate_by_name=True):
     """The mapping between an asset-centric ID and a data modeling instance ID.
     Args
         resource_type (str): The asset-centric type of the resource (e.g., "asset", "event", "timeseries").
@@ -28,7 +42,7 @@ class MigrationMapping(BaseModel, alias_generator=to_camel_case, extra="ignore")
     """
 
     resource_type: str
-    instance_id: NodeId
+    instance_id: InstanceId
     id: int
     data_set_id: int | None = None
     ingestion_view: str | None = None
@@ -46,6 +60,7 @@ class MigrationMapping(BaseModel, alias_generator=to_camel_case, extra="ignore")
         raise ToolkitValueError(f"No default ingestion view specified for resource type '{self.resource_type}'")
 
     def as_asset_centric_id(self) -> AssetCentricId:
+        # MyPy fails to understand that resource_type is AssetCentricKindExtended in subclasses
         return AssetCentricId(resource_type=self.resource_type, id_=self.id)  # type: ignore[arg-type]
 
     @model_validator(mode="before")
@@ -77,12 +92,6 @@ class MigrationMapping(BaseModel, alias_generator=to_camel_case, extra="ignore")
             return ViewId.load(v)
         return v
 
-    @field_validator("instance_id", mode="before")
-    def _validate_instance_id(cls, v: Any) -> Any:
-        if isinstance(v, dict):
-            return NodeId.load(v)
-        return v
-
 
 class MigrationMappingList(ModelList[MigrationMapping]):
     @classmethod
@@ -103,14 +112,22 @@ class MigrationMappingList(ModelList[MigrationMapping]):
 
     def as_node_ids(self) -> list[NodeId]:
         """Return a list of NodeIds from the migration mappings."""
-        return [mapping.instance_id for mapping in self]
+        return [mapping.instance_id for mapping in self if isinstance(mapping.instance_id, NodeId)]
+
+    def as_edge_ids(self) -> list[EdgeId]:
+        """Return a list of EdgeIds from the migration mappings."""
+        return [mapping.instance_id for mapping in self if isinstance(mapping.instance_id, EdgeId)]
 
     def spaces(self) -> set[str]:
         """Return a set of spaces from the migration mappings."""
         return {mapping.instance_id.space for mapping in self}
 
     def as_pending_ids(self) -> list[PendingInstanceId]:
-        return [PendingInstanceId(pending_instance_id=mapping.instance_id, id=mapping.id) for mapping in self]
+        return [
+            PendingInstanceId(pending_instance_id=mapping.instance_id, id=mapping.id)
+            for mapping in self
+            if isinstance(mapping.instance_id, NodeId)
+        ]
 
     def get_data_set_ids(self) -> set[int]:
         """Return a list of data set IDs from the migration mappings."""
@@ -121,13 +138,17 @@ class MigrationMappingList(ModelList[MigrationMapping]):
         return {mapping.id: mapping for mapping in self}
 
     @classmethod
-    def read_csv_file(cls, filepath: Path, resource_type: str | None = None) -> "MigrationMappingList":
+    def read_csv_file(
+        cls, filepath: Path, resource_type: AssetCentricKindExtended | None = None
+    ) -> "MigrationMappingList":
         if cls is not MigrationMappingList or resource_type is None:
             return super().read_csv_file(filepath)
         cls_by_resource_type: dict[str, type[MigrationMappingList]] = {
-            "asset": AssetMigrationMappingList,
-            "timeseries": TimeSeriesMigrationMappingList,
-            "file": FileMigrationMappingList,
+            "Assets": AssetMigrationMappingList,
+            "TimeSeries": TimeSeriesMigrationMappingList,
+            "FileMetadata": FileMigrationMappingList,
+            "Events": EventMigrationMappingList,
+            "Annotations": AnnotationMigrationMappingList,
         }
         if resource_type not in cls_by_resource_type:
             raise ToolkitValueError(
@@ -136,16 +157,53 @@ class MigrationMappingList(ModelList[MigrationMapping]):
         return cls_by_resource_type[resource_type].read_csv_file(filepath, resource_type=None)
 
 
+def _validate_node_id(value: Any) -> Any:
+    if isinstance(value, dict):
+        return NodeId.load(value)
+    return value
+
+
 class AssetMapping(MigrationMapping):
     resource_type: Literal["asset"] = "asset"
+    instance_id: Annotated[NodeId, BeforeValidator(_validate_node_id)]
+
+
+class EventMapping(MigrationMapping):
+    resource_type: Literal["event"] = "event"
+    instance_id: Annotated[NodeId, BeforeValidator(_validate_node_id)]
 
 
 class TimeSeriesMapping(MigrationMapping):
     resource_type: Literal["timeseries"] = "timeseries"
+    instance_id: Annotated[NodeId, BeforeValidator(_validate_node_id)]
 
 
 class FileMapping(MigrationMapping):
     resource_type: Literal["file"] = "file"
+    instance_id: Annotated[NodeId, BeforeValidator(_validate_node_id)]
+
+
+class AnnotationMapping(MigrationMapping):
+    resource_type: Literal["annotation"] = "annotation"
+    instance_id: EdgeId
+    annotation_type: Literal["diagrams.AssetLink", "diagrams.FileLink"] | None = None
+
+    def get_ingestion_view(self) -> str:
+        """Get the ingestion view for the mapping. If not specified, return the default ingestion view."""
+        if self.ingestion_view:
+            return self.ingestion_view
+        elif self.annotation_type == "diagrams.AssetLink":
+            return ASSET_ANNOTATIONS_ID
+        elif self.annotation_type == "diagrams.FileLink":
+            return FILE_ANNOTATIONS_ID
+        else:
+            raise ToolkitValueError("Cannot determine default ingestion view for annotation without annotation_type")
+
+    @field_validator("instance_id", mode="before")
+    def _validate_instance_id(cls, v: Any) -> Any:
+        if isinstance(v, dict):
+            return EdgeId.load(v)
+        return v
 
 
 class AssetMigrationMappingList(MigrationMappingList):
@@ -154,6 +212,12 @@ class AssetMigrationMappingList(MigrationMappingList):
         return AssetMapping
 
 
+class EventMigrationMappingList(MigrationMappingList):
+    @classmethod
+    def _get_base_model_cls(cls) -> type[EventMapping]:
+        return EventMapping
+
+
 class FileMigrationMappingList(MigrationMappingList):
     @classmethod
     def _get_base_model_cls(cls) -> type[FileMapping]:
@@ -164,3 +228,36 @@ class TimeSeriesMigrationMappingList(MigrationMappingList):
     @classmethod
     def _get_base_model_cls(cls) -> type[TimeSeriesMapping]:
         return TimeSeriesMapping
+
+
+class AnnotationMigrationMappingList(MigrationMappingList):
+    @classmethod
+    def _get_base_model_cls(cls) -> type[AnnotationMapping]:
+        return AnnotationMapping
+
+
+@dataclass
+class AssetCentricMapping(Generic[T_AssetCentricResourceExtended], WriteableCogniteResource[InstanceApply]):
+    mapping: MigrationMapping
+    resource: T_AssetCentricResourceExtended
+
+    def as_write(self) -> InstanceApply:
+        raise NotImplementedError()
+
+    def dump(self, camel_case: bool = True) -> dict[str, JsonVal]:
+        mapping = self.mapping.model_dump(exclude_unset=True, by_alias=camel_case)
+        # Ensure that resource type is always included, even if unset.
+        mapping["resourceType" if camel_case else "resource_type"] = self.mapping.resource_type
+        return {
+            "mapping": mapping,
+            "resource": self.resource.dump(camel_case=camel_case),
+        }
+
+
+class AssetCentricMappingList(
+    WriteableCogniteResourceList[InstanceApply, AssetCentricMapping[T_AssetCentricResourceExtended]]
+):
+    _RESOURCE: type = AssetCentricMapping
+
+    def as_write(self) -> InstanceApplyList:
+        return InstanceApplyList([item.as_write() for item in self])

cognite_toolkit/_cdf_tk/commands/_migrate/data_mapper.py

@@ -1,26 +1,55 @@
 from abc import ABC, abstractmethod
-from typing import Generic
+from collections import defaultdict
+from collections.abc import Callable, Sequence
+from typing import Generic, cast
+from uuid import uuid4
 
-from cognite.client.data_classes._base import (
-    T_CogniteResourceList,
+from cognite.client.data_classes.data_modeling import (
+    EdgeApply,
+    InstanceApply,
+    NodeApply,
+    NodeId,
+    View,
+    ViewId,
 )
-from cognite.client.data_classes.data_modeling import View, ViewId
+from cognite.client.exceptions import CogniteException
 
 from cognite_toolkit._cdf_tk.client import ToolkitClient
-from cognite_toolkit._cdf_tk.client.data_classes.instances import InstanceApplyList
-from cognite_toolkit._cdf_tk.client.data_classes.migration import ResourceViewMapping
-from cognite_toolkit._cdf_tk.commands._migrate.adapter import (
-    AssetCentricMappingList,
-    MigrationSelector,
+from cognite_toolkit._cdf_tk.client.data_classes.canvas import (
+    ContainerReferenceApply,
+    FdmInstanceContainerReferenceApply,
+    IndustrialCanvas,
+    IndustrialCanvasApply,
 )
-from cognite_toolkit._cdf_tk.commands._migrate.conversion import asset_centric_to_dm
-from cognite_toolkit._cdf_tk.commands._migrate.issues import MigrationIssue
-from cognite_toolkit._cdf_tk.exceptions import ToolkitValueError
-from cognite_toolkit._cdf_tk.storageio._base import T_Selector, T_WritableCogniteResourceList
+from cognite_toolkit._cdf_tk.client.data_classes.charts import Chart, ChartWrite
+from cognite_toolkit._cdf_tk.client.data_classes.charts_data import (
+    ChartCoreTimeseries,
+    ChartSource,
+    ChartTimeseries,
+)
+from cognite_toolkit._cdf_tk.client.data_classes.migration import ResourceViewMappingApply
+from cognite_toolkit._cdf_tk.commands._migrate.conversion import DirectRelationCache, asset_centric_to_dm
+from cognite_toolkit._cdf_tk.commands._migrate.data_classes import AssetCentricMapping
+from cognite_toolkit._cdf_tk.commands._migrate.default_mappings import create_default_mappings
+from cognite_toolkit._cdf_tk.commands._migrate.issues import (
+    CanvasMigrationIssue,
+    ChartMigrationIssue,
+    ConversionIssue,
+    MigrationIssue,
+)
+from cognite_toolkit._cdf_tk.commands._migrate.selectors import AssetCentricMigrationSelector
+from cognite_toolkit._cdf_tk.constants import MISSING_INSTANCE_SPACE
+from cognite_toolkit._cdf_tk.exceptions import ToolkitMigrationError, ToolkitValueError
+from cognite_toolkit._cdf_tk.protocols import T_ResourceRequest, T_ResourceResponse
+from cognite_toolkit._cdf_tk.storageio._base import T_Selector
+from cognite_toolkit._cdf_tk.storageio.selectors import CanvasSelector, ChartSelector
 from cognite_toolkit._cdf_tk.utils import humanize_collection
+from cognite_toolkit._cdf_tk.utils.useful_types import (
+    T_AssetCentricResourceExtended,
+)
 
 
-class DataMapper(Generic[T_Selector, T_WritableCogniteResourceList, T_CogniteResourceList], ABC):
+class DataMapper(Generic[T_Selector, T_ResourceResponse, T_ResourceRequest], ABC):
     def prepare(self, source_selector: T_Selector) -> None:
         """Prepare the data mapper with the given source selector.
 
@@ -32,7 +61,7 @@ class DataMapper(Generic[T_Selector, T_WritableCogniteResourceList, T_CogniteRes
         pass
 
     @abstractmethod
-    def map_chunk(self, source: T_WritableCogniteResourceList) -> tuple[T_CogniteResourceList, list[MigrationIssue]]:
+    def map(self, source: Sequence[T_ResourceResponse]) -> Sequence[tuple[T_ResourceRequest | None, MigrationIssue]]:
         """Map a chunk of source data to the target format.
 
         Args:
@@ -45,23 +74,28 @@ class DataMapper(Generic[T_Selector, T_WritableCogniteResourceList, T_CogniteRes
         raise NotImplementedError("Subclasses must implement this method.")
 
 
-class AssetCentricMapper(DataMapper[MigrationSelector, AssetCentricMappingList, InstanceApplyList]):
+class AssetCentricMapper(
+    DataMapper[AssetCentricMigrationSelector, AssetCentricMapping[T_AssetCentricResourceExtended], InstanceApply]
+):
     def __init__(self, client: ToolkitClient) -> None:
         self.client = client
         self._ingestion_view_by_id: dict[ViewId, View] = {}
-        self._view_mapping_by_id: dict[str, ResourceViewMapping] = {}
+        self._view_mapping_by_id: dict[str, ResourceViewMappingApply] = {}
+        self._direct_relation_cache = DirectRelationCache(client)
 
-    def prepare(self, source_selector: MigrationSelector) -> None:
-        ingestion_view_ids = source_selector.get_ingestion_views()
+    def prepare(self, source_selector: AssetCentricMigrationSelector) -> None:
+        ingestion_view_ids = source_selector.get_ingestion_mappings()
         ingestion_views = self.client.migration.resource_view_mapping.retrieve(ingestion_view_ids)
-        self._view_mapping_by_id = {view.external_id: view for view in ingestion_views}
+        defaults = {mapping.external_id: mapping for mapping in create_default_mappings()}
+        # Custom mappings from CDF override the default mappings
+        self._view_mapping_by_id = defaults | {view.external_id: view.as_write() for view in ingestion_views}
         missing_mappings = set(ingestion_view_ids) - set(self._view_mapping_by_id.keys())
         if missing_mappings:
             raise ToolkitValueError(
                 f"The following ingestion views were not found: {humanize_collection(missing_mappings)}"
             )
 
-        view_ids = list({view.view_id for view in ingestion_views})
+        view_ids = list({mapping.view_id for mapping in self._view_mapping_by_id.values()})
         views = self.client.data_modeling.views.retrieve(view_ids)
         self._ingestion_view_by_id = {view.as_id(): view for view in views}
         missing_views = set(view_ids) - set(self._ingestion_view_by_id.keys())
@@ -70,28 +104,282 @@ class AssetCentricMapper(DataMapper[MigrationSelector, AssetCentricMappingList,
                 f"The following ingestion views were not found in Data Modeling: {humanize_collection(missing_views)}"
             )
 
-    def map_chunk(self, source: AssetCentricMappingList) -> tuple[InstanceApplyList, list[MigrationIssue]]:
+    def map(
+        self, source: Sequence[AssetCentricMapping[T_AssetCentricResourceExtended]]
+    ) -> Sequence[tuple[InstanceApply | None, ConversionIssue]]:
         """Map a chunk of asset-centric data to InstanceApplyList format."""
-        instances = InstanceApplyList([])
-        issues: list[MigrationIssue] = []
+        # We update the direct relation cache in bulk for all resources in the chunk.
+        self._direct_relation_cache.update(item.resource for item in source)
+        output: list[tuple[InstanceApply | None, ConversionIssue]] = []
+        for item in source:
+            instance, conversion_issue = self._map_single_item(item)
+            output.append((instance, conversion_issue))
+        return output
+
+    def _map_single_item(
+        self, item: AssetCentricMapping[T_AssetCentricResourceExtended]
+    ) -> tuple[NodeApply | EdgeApply | None, ConversionIssue]:
+        mapping = item.mapping
+        ingestion_view = mapping.get_ingestion_view()
+        try:
+            view_source = self._view_mapping_by_id[ingestion_view]
+            view_properties = self._ingestion_view_by_id[view_source.view_id].properties
+        except KeyError as e:
+            raise RuntimeError(
+                f"Failed to lookup mapping or view for ingestion view '{ingestion_view}'. Did you forget to call .prepare()?"
+            ) from e
+        instance, conversion_issue = asset_centric_to_dm(
+            item.resource,
+            instance_id=mapping.instance_id,
+            view_source=view_source,
+            view_properties=view_properties,
+            direct_relation_cache=self._direct_relation_cache,
+        )
+        if mapping.instance_id.space == MISSING_INSTANCE_SPACE:
+            conversion_issue.missing_instance_space = f"Missing instance space for dataset ID {mapping.data_set_id!r}"
+        return instance, conversion_issue
+
+
+class ChartMapper(DataMapper[ChartSelector, Chart, ChartWrite]):
+    def __init__(self, client: ToolkitClient) -> None:
+        self.client = client
+
+    def map(self, source: Sequence[Chart]) -> Sequence[tuple[ChartWrite | None, MigrationIssue]]:
+        self._populate_cache(source)
+        output: list[tuple[ChartWrite | None, MigrationIssue]] = []
         for item in source:
-            mapping = item.mapping
-            ingestion_view = mapping.get_ingestion_view()
+            mapped_item, issue = self._map_single_item(item)
+            output.append((mapped_item, issue))
+        return output
+
+    def _populate_cache(self, source: Sequence[Chart]) -> None:
+        """Populate the internal cache with timeseries from the source charts.
+
+        Note that the consumption views are also cached as part of the timeseries lookup.
+        """
+        timeseries_ids: set[int] = set()
+        timeseries_external_ids: set[str] = set()
+        for chart in source:
+            for item in chart.data.time_series_collection or []:
+                if item.ts_id:
+                    timeseries_ids.add(item.ts_id)
+                if item.ts_external_id:
+                    timeseries_external_ids.add(item.ts_external_id)
+        if timeseries_ids:
+            self.client.migration.lookup.time_series(list(timeseries_ids))
+        if timeseries_external_ids:
+            self.client.migration.lookup.time_series(external_id=list(timeseries_external_ids))
+
+    def _map_single_item(self, item: Chart) -> tuple[ChartWrite | None, ChartMigrationIssue]:
+        issue = ChartMigrationIssue(chart_external_id=item.external_id)
+        time_series_collection = item.data.time_series_collection or []
+        timeseries_core_collection = self._create_timeseries_core_collection(time_series_collection, issue)
+        if issue.has_issues:
+            return None, issue
+
+        updated_source_collection = self._update_source_collection(
+            item.data.source_collection or [], time_series_collection, timeseries_core_collection
+        )
+
+        mapped_chart = item.as_write()
+        mapped_chart.data.core_timeseries_collection = timeseries_core_collection
+        mapped_chart.data.time_series_collection = None
+        mapped_chart.data.source_collection = updated_source_collection
+        return mapped_chart, issue
+
+    def _create_timeseries_core_collection(
+        self, time_series_collection: list[ChartTimeseries], issue: ChartMigrationIssue
+    ) -> list[ChartCoreTimeseries]:
+        timeseries_core_collection: list[ChartCoreTimeseries] = []
+        for ts_item in time_series_collection or []:
+            node_id, consumer_view_id = self._get_node_id_consumer_view_id(ts_item)
+
+            if node_id is None:
+                if ts_item.ts_id is not None:
+                    issue.missing_timeseries_ids.append(ts_item.ts_id)
+                elif ts_item.ts_external_id is not None:
+                    issue.missing_timeseries_external_ids.append(ts_item.ts_external_id)
+                else:
+                    issue.missing_timeseries_identifier.append(ts_item.id or "unknown")
+                continue
+
+            core_timeseries = self._create_new_timeseries_core(ts_item, node_id, consumer_view_id)
+            timeseries_core_collection.append(core_timeseries)
+        return timeseries_core_collection
+
+    def _create_new_timeseries_core(
+        self, ts_item: ChartTimeseries, node_id: NodeId, consumer_view_id: ViewId | None
+    ) -> ChartCoreTimeseries:
+        dumped = ts_item.model_dump(mode="json", by_alias=True, exclude_unset=True)
+        dumped["nodeReference"] = node_id
+        dumped["viewReference"] = consumer_view_id
+        new_uuid = str(uuid4())
+        dumped["id"] = new_uuid
+        dumped["type"] = "coreTimeseries"
+        # We ignore extra here to only include the fields that are shared between ChartTimeseries and ChartCoreTimeseries
+        core_timeseries = ChartCoreTimeseries.model_validate(dumped, extra="ignore")
+        return core_timeseries
+
+    def _get_node_id_consumer_view_id(self, ts_item: ChartTimeseries) -> tuple[NodeId | None, ViewId | None]:
+        """Look up the node ID and consumer view ID for a given timeseries item.
+
+        Prioritizes lookup by internal ID, then by external ID.
+
+        Args:
+            ts_item: The ChartTimeseries item to look up.
+
+        Returns:
+            A tuple containing the consumer view ID and node ID, or None if not found.
+        """
+        node_id: NodeId | None = None
+        consumer_view_id: ViewId | None = None
+        for id_name, id_value in [("id", ts_item.ts_id), ("external_id", ts_item.ts_external_id)]:
+            if id_value is None:
+                continue
+            arg = {id_name: id_value}
+            node_id = self.client.migration.lookup.time_series(**arg)  # type: ignore[arg-type]
+            consumer_view_id = self.client.migration.lookup.time_series.consumer_view(**arg)  # type: ignore[arg-type]
+            if node_id is not None:
+                break
+        return node_id, consumer_view_id
+
+    def _update_source_collection(
+        self,
+        source_collection: list[ChartSource],
+        time_series_collection: list[ChartTimeseries],
+        timeseries_core_collection: list[ChartCoreTimeseries],
+    ) -> list[ChartSource]:
+        remove_ids = {ts_item.id for ts_item in time_series_collection if ts_item.id is not None}
+        updated_source_collection = [ts_item for ts_item in source_collection if ts_item.id not in remove_ids]
+        for core_ts_item in timeseries_core_collection:
+            # We cast there two as we set them in the _create_timeseries_core_collection method
+            new_source_item = ChartSource(id=cast(str, core_ts_item.id), type=cast(str, core_ts_item.type))
+            updated_source_collection.append(new_source_item)
+        return updated_source_collection
+
+
+class CanvasMapper(DataMapper[CanvasSelector, IndustrialCanvas, IndustrialCanvasApply]):
+    # Note sequences are not supported in Canvas, so we do not include them here.
+    asset_centric_resource_types = tuple(("asset", "event", "timeseries", "file"))
+    DEFAULT_ASSET_VIEW = ViewId("cdf_cdm", "CogniteAsset", "v1")
+    DEFAULT_EVENT_VIEW = ViewId("cdf_cdm", "CogniteActivity", "v1")
+    DEFAULT_FILE_VIEW = ViewId("cdf_cdm", "CogniteFile", "v1")
+    DEFAULT_TIMESERIES_VIEW = ViewId("cdf_cdm", "CogniteTimeSeries", "v1")
+
+    def __init__(self, client: ToolkitClient, dry_run: bool, skip_on_missing_ref: bool = False) -> None:
+        self.client = client
+        self.dry_run = dry_run
+        self.skip_on_missing_ref = skip_on_missing_ref
+
+    def map(self, source: Sequence[IndustrialCanvas]) -> Sequence[tuple[IndustrialCanvasApply | None, MigrationIssue]]:
+        self._populate_cache(source)
+        output: list[tuple[IndustrialCanvasApply | None, MigrationIssue]] = []
+        for item in source:
+            mapped_item, issue = self._map_single_item(item)
+            output.append((mapped_item, issue))
+        return output
+
+    @property
+    def lookup_methods(self) -> dict[str, Callable]:
+        return {
+            "asset": self.client.migration.lookup.assets,
+            "event": self.client.migration.lookup.events,
+            "timeseries": self.client.migration.lookup.time_series,
+            "file": self.client.migration.lookup.files,
+        }
+
+    def _populate_cache(self, source: Sequence[IndustrialCanvas]) -> None:
+        """Populate the internal cache with references from the source canvases.
+
+        Note that the consumption views are also cached as part of the timeseries lookup.
+        """
+        ids_by_type: dict[str, set[int]] = defaultdict(set)
+        for canvas in source:
+            for ref in canvas.container_references or []:
+                if ref.container_reference_type in self.asset_centric_resource_types:
+                    ids_by_type[ref.container_reference_type].add(ref.resource_id)
+
+        for resource_type, lookup_method in self.lookup_methods.items():
+            ids = ids_by_type.get(resource_type)
+            if ids:
+                lookup_method(list(ids))
+
+    def _get_node_id(self, resource_id: int, resource_type: str) -> NodeId | None:
+        """Look up the node ID for a given resource ID and type."""
+        try:
+            return self.lookup_methods[resource_type](resource_id)
+        except KeyError:
+            raise ToolkitValueError(f"Unsupported resource type '{resource_type}' for container reference migration.")
+
+    def _get_consumer_view_id(self, resource_id: int, resource_type: str) -> ViewId:
+        """Look up the consumer view ID for a given resource ID and type."""
+        lookup_map = {
+            "asset": (self.client.migration.lookup.assets.consumer_view, self.DEFAULT_ASSET_VIEW),
+            "event": (self.client.migration.lookup.events.consumer_view, self.DEFAULT_EVENT_VIEW),
+            "timeseries": (self.client.migration.lookup.time_series.consumer_view, self.DEFAULT_TIMESERIES_VIEW),
+            "file": (self.client.migration.lookup.files.consumer_view, self.DEFAULT_FILE_VIEW),
+        }
+        if lookup_tuple := lookup_map.get(resource_type):
+            method, fallback = lookup_tuple
+            return method(resource_id) or fallback
+
+        raise ToolkitValueError(f"Unsupported resource type '{resource_type}' for container reference migration.")
+
+    def _map_single_item(self, canvas: IndustrialCanvas) -> tuple[IndustrialCanvasApply | None, CanvasMigrationIssue]:
+        update = canvas.as_write()
+        issue = CanvasMigrationIssue(canvas_external_id=canvas.canvas.external_id, canvas_name=canvas.canvas.name)
+
+        remaining_container_references: list[ContainerReferenceApply] = []
+        new_fdm_references: list[FdmInstanceContainerReferenceApply] = []
+        for ref in update.container_references or []:
+            if ref.container_reference_type not in self.asset_centric_resource_types:
+                remaining_container_references.append(ref)
+                continue
+            node_id = self._get_node_id(ref.resource_id, ref.container_reference_type)
+            if node_id is None:
+                issue.missing_reference_ids.append(ref.as_asset_centric_id())
+            else:
+                consumer_view = self._get_consumer_view_id(ref.resource_id, ref.container_reference_type)
+                fdm_ref = self.migrate_container_reference(ref, canvas.canvas.external_id, node_id, consumer_view)
+                new_fdm_references.append(fdm_ref)
+        if issue.missing_reference_ids and self.skip_on_missing_ref:
+            return None, issue
+
+        update.container_references = remaining_container_references
+        update.fdm_instance_container_references.extend(new_fdm_references)
+        if not self.dry_run:
+            backup = canvas.as_write().create_backup()
             try:
-                view_source = self._view_mapping_by_id[ingestion_view]
-                view_properties = self._ingestion_view_by_id[view_source.view_id].properties
-            except KeyError as e:
-                raise RuntimeError(
-                    f"Failed to lookup mapping or view for ingestion view '{ingestion_view}'. Did you forget to call .prepare()?"
+                self.client.canvas.industrial.create(backup)
+            except CogniteException as e:
+                raise ToolkitMigrationError(
+                    f"Failed to create backup for canvas '{canvas.canvas.name}': {e!s}. "
                 ) from e
-            instance, conversion_issue = asset_centric_to_dm(
-                item.resource,
-                instance_id=mapping.instance_id,
-                view_source=view_source,
-                view_properties=view_properties,
-            )
 
-            instances.append(instance)
-            if conversion_issue.has_issues:
-                issues.append(conversion_issue)
-        return instances, issues
+        return update, issue
+
+    @classmethod
+    def migrate_container_reference(
+        cls, reference: ContainerReferenceApply, canvas_external_id: str, instance_id: NodeId, consumer_view: ViewId
+    ) -> FdmInstanceContainerReferenceApply:
+        """Migrate a single container reference by replacing the asset-centric ID with the data model instance ID."""
+        new_id = str(uuid4())
+        new_external_id = f"{canvas_external_id}_{new_id}"
+        return FdmInstanceContainerReferenceApply(
+            external_id=new_external_id,
+            id_=new_id,
+            container_reference_type="fdmInstance",
+            instance_space=instance_id.space,
+            instance_external_id=instance_id.external_id,
+            view_space=consumer_view.space,
+            view_external_id=consumer_view.external_id,
+            view_version=consumer_view.version,
+            label=reference.label,
+            properties_=reference.properties_,
+            x=reference.x,
+            y=reference.y,
+            width=reference.width,
+            height=reference.height,
+            max_width=reference.max_width,
+            max_height=reference.max_height,
+        )