cognite-toolkit 0.5.97__py3-none-any.whl → 0.7.34__py3-none-any.whl

cognite_toolkit/_cdf_tk/resource_classes/transformations.py

@@ -4,22 +4,11 @@ from cognite.client.data_classes import TransformationWrite
 from pydantic import Field, field_validator, model_serializer
 from pydantic_core.core_schema import SerializationInfo, SerializerFunctionWrapHandler
 
-from .base import BaseModelResource, ToolkitResource
+from .authentication import AuthenticationClientIdSecret, OIDCCredential
+from .base import ToolkitResource
 from .transformation_destination import Destination
 
 
-class AuthenticationClientIdSecret(BaseModelResource):
-    client_id: str = Field(description="Client Id.")
-    client_secret: str = Field(description="Client Secret.")
-
-
-class OIDCCredential(AuthenticationClientIdSecret):
-    scopes: str | list[str] | None = Field(default=None, description="Scopes for the authentication.")
-    token_uri: str = Field(description="OAuth token url.")
-    cdf_project_name: str = Field(description="CDF project name.")
-    audience: str | None = Field(default=None, description="Audience for the authentication.")
-
-
 class TransformationYAML(ToolkitResource):
     _cdf_resource = TransformationWrite
     external_id: str = Field(description="The external ID provided by the client.")

cognite_toolkit/_cdf_tk/resource_classes/view_field_definitions.py

@@ -7,10 +7,10 @@ from pydantic import Field, ModelWrapValidatorHandler, model_serializer, model_v
 from pydantic_core.core_schema import SerializerFunctionWrapHandler
 
 from cognite_toolkit._cdf_tk.constants import (
-    CONTAINER_AND_VIEW_EXTERNAL_ID_PATTERN,
     CONTAINER_AND_VIEW_PROPERTIES_IDENTIFIER_PATTERN,
+    DM_EXTERNAL_ID_PATTERN,
+    DM_VERSION_PATTERN,
     SPACE_FORMAT_PATTERN,
-    VIEW_VERSION_PATTERN,
 )
 from cognite_toolkit._cdf_tk.utils.collection import humanize_collection
 
@@ -25,7 +25,7 @@ else:
 KEY_PATTERN = re.compile(CONTAINER_AND_VIEW_PROPERTIES_IDENTIFIER_PATTERN)
 
 
-class ViewReference(BaseModelResource):
+class ViewReference(BaseModelResource, populate_by_name=True):
     type: Literal["view"] = "view"
     space: str = Field(
         description="Id of the space that the view belongs to.",
@@ -37,27 +37,26 @@ class ViewReference(BaseModelResource):
         description="External-id of the view.",
         min_length=1,
         max_length=255,
-        pattern=CONTAINER_AND_VIEW_EXTERNAL_ID_PATTERN,
+        pattern=DM_EXTERNAL_ID_PATTERN,
     )
     version: str = Field(
         description="Version of the view.",
         max_length=43,
-        pattern=VIEW_VERSION_PATTERN,
+        pattern=DM_VERSION_PATTERN,
     )
 
 
 class DirectRelationReference(BaseModelResource):
     space: str = Field(
-        description="Id of the space that the view belongs to.",
+        description="Id of the space that the instance belongs to.",
         min_length=1,
         max_length=43,
         pattern=SPACE_FORMAT_PATTERN,
     )
     external_id: str = Field(
-        description="External-id of the view.",
+        description="External-id of the instance.",
         min_length=1,
         max_length=255,
-        pattern=CONTAINER_AND_VIEW_EXTERNAL_ID_PATTERN,
     )
 
 

cognite_toolkit/_cdf_tk/resource_classes/views.py

@@ -5,12 +5,12 @@ from pydantic import Field, field_validator, model_serializer
 from pydantic_core.core_schema import SerializationInfo, SerializerFunctionWrapHandler
 
 from cognite_toolkit._cdf_tk.constants import (
-    CONTAINER_AND_VIEW_EXTERNAL_ID_PATTERN,
     CONTAINER_AND_VIEW_PROPERTIES_IDENTIFIER_PATTERN,
+    DM_EXTERNAL_ID_PATTERN,
+    DM_VERSION_PATTERN,
     FORBIDDEN_CONTAINER_AND_VIEW_EXTERNAL_IDS,
     FORBIDDEN_CONTAINER_AND_VIEW_PROPERTIES_IDENTIFIER,
     SPACE_FORMAT_PATTERN,
-    VIEW_VERSION_PATTERN,
 )
 from cognite_toolkit._cdf_tk.utils.collection import humanize_collection
 
@@ -31,12 +31,12 @@ class ViewYAML(ToolkitResource):
         description="External-id of the view.",
         min_length=1,
         max_length=255,
-        pattern=CONTAINER_AND_VIEW_EXTERNAL_ID_PATTERN,
+        pattern=DM_EXTERNAL_ID_PATTERN,
     )
     version: str = Field(
         description="Version of the view.",
         max_length=43,
-        pattern=VIEW_VERSION_PATTERN,
+        pattern=DM_VERSION_PATTERN,
     )
     name: str | None = Field(
         default=None,

cognite_toolkit/_cdf_tk/resource_classes/workflow_trigger.py

@@ -0,0 +1,115 @@
+import sys
+from types import MappingProxyType
+from typing import Any, ClassVar, cast
+
+from cognite.client.data_classes import WorkflowTrigger
+from pydantic import Field, JsonValue, ModelWrapValidatorHandler, model_serializer, model_validator
+from pydantic_core.core_schema import SerializationInfo, SerializerFunctionWrapHandler
+
+from cognite_toolkit._cdf_tk.utils import humanize_collection
+
+from .authentication import AuthenticationClientIdSecret
+from .base import BaseModelResource, ToolkitResource
+
+if sys.version_info < (3, 11):
+    from typing_extensions import Self
+else:
+    from typing import Self
+
+
+class TriggerRuleYAML(BaseModelResource):
+    _trigger_type: ClassVar[str]
+
+    @model_validator(mode="wrap")
+    @classmethod
+    def find_trigger_type(
+        cls, data: "dict[str, Any] | TriggerRuleYAML", handler: ModelWrapValidatorHandler[Self]
+    ) -> Self:
+        if isinstance(data, TriggerRuleYAML):
+            return cast(Self, data)
+        if not isinstance(data, dict):
+            raise ValueError(f"Invalid trigger rule data '{type(data)}' expected dict")
+
+        if cls is not TriggerRuleYAML:
+            # We are already in a subclass, so just validate as usual
+            return handler(data)
+        # If not we need to find the right subclass based on the triggerType field.
+        if "triggerType" not in data:
+            raise ValueError("Invalid trigger rule data missing 'triggerType' key")
+        trigger_type = data["triggerType"]
+        if trigger_type not in _TRIGGER_CLS_BY_NAME:
+            raise ValueError(
+                f"invalid trigger type '{trigger_type}'. Expected one of {humanize_collection(_TRIGGER_CLS_BY_NAME.keys(), bind_word='or')}"
+            )
+        cls_ = _TRIGGER_CLS_BY_NAME[trigger_type]
+        return cast(Self, cls_.model_validate({k: v for k, v in data.items() if k != "triggerType"}))
+
+    @model_serializer(mode="wrap", when_used="always", return_type=dict)
+    def include_trigger_type(self, handler: SerializerFunctionWrapHandler) -> dict:
+        if self._trigger_type is None:
+            raise ValueError("Trigger type is not set")
+        serialized_data = handler(self)
+        serialized_data["triggerType"] = self._trigger_type
+        return serialized_data
+
+
+class ScheduleTrigger(TriggerRuleYAML):
+    _trigger_type = "schedule"
+    cron_expression: str = Field(
+        description="A cron expression (UNIX format) specifying when the trigger should be executed. Use https://crontab.guru/ to create a cron expression. The API may adjust the exact timing of cron job executions to distribute the backend load more evenly. However, it will aim to maintain the overall frequency of executions as specified in the cron expression.",
+    )
+    timezone: str = Field(
+        "UTC",
+        description="Specifies the IANA time zone in which the cron expression is evaluated. Time zones must be valid as listed in https://docs.oracle.com/cd/E72987_01/wcs/tag-ref/MISC/TimeZones.html.",
+    )
+
+
+class DataModelingTrigger(TriggerRuleYAML):
+    _trigger_type = "dataModeling"
+    data_modeling_query: JsonValue
+    batch_size: int = Field(
+        ge=100, le=1_000, description="The maximum number of items to pass to a workflow execution."
+    )
+    batch_timeout: int = Field(
+        ge=60,
+        le=86_400,
+        description="The maximum time in seconds to wait for the batch to be filled before passing it to a workflow execution.",
+    )
+
+
+class WorkflowTriggerYAML(ToolkitResource):
+    _cdf_resource = WorkflowTrigger
+    external_id: str = Field(
+        max_length=255,
+        description="Identifier for a trigger. Must be unique for the project. "
+        "No trailing or leading whitespace and no null characters allowed.",
+    )
+    trigger_rule: TriggerRuleYAML
+    input: JsonValue | None = None
+    metadata: dict[str, str] | None = None
+    workflow_external_id: str = Field(
+        max_length=255,
+        description="Identifier for a workflow. Must be unique for the project. "
+        "No trailing or leading whitespace and no null characters allowed.",
+    )
+    workflow_version: str = Field(
+        max_length=255,
+        description="Identifier for a version. Must be unique for the workflow. No trailing or"
+        " leading whitespace and no null characters allowed.",
+    )
+    authentication: AuthenticationClientIdSecret = Field(description="Credentials required for the authentication.")
+
+    @model_serializer(mode="wrap")
+    def serialize_trigger_rules(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> dict:
+        # Trigger rules are serialized as empty dicts [{}, {}, ...]
+        # This issue arises because Pydantic's serialization mechanism doesn't automatically
+        # handle polymorphic serialization for subclasses of TriggerRuleYAML.
+        # To address this, we include the below to explicitly calling model dump on the trigger rule
+        serialized_data = handler(self)
+        serialized_data["triggerRule"] = self.trigger_rule.model_dump(**vars(info))
+        return serialized_data
+
+
+_TRIGGER_CLS_BY_NAME: MappingProxyType[str, type[TriggerRuleYAML]] = MappingProxyType(
+    {s._trigger_type: s for s in TriggerRuleYAML.__subclasses__()}
+)

cognite_toolkit/_cdf_tk/resource_classes/workflow_version.py

@@ -0,0 +1,233 @@
+from abc import ABC
+from typing import Annotated, Literal
+
+from cognite.client.data_classes import WorkflowVersionUpsert
+from pydantic import Field, JsonValue
+
+from .base import BaseModelResource, ToolkitResource
+
+
+class WorkflowVersionId(BaseModelResource):
+    workflow_external_id: str = Field(
+        max_length=255,
+        description="Identifier for a workflow. Must be unique for the project. No trailing or leading whitespace and no null characters allowed.",
+    )
+    version: str = Field(
+        max_length=255,
+        description="Identifier for a version. Must be unique for the workflow. No trailing or leading whitespace and no null characters allowed.",
+    )
+
+
+class CogniteFunctionRef(BaseModelResource):
+    external_id: str = Field(
+        description="The external id of the Cognite Function in the project. This can be either a function external ID or a reference like ${myTaskExternalId.output.someKey}"
+    )
+    data: str | JsonValue | None = Field(
+        None, description="Input data that will be passed to the Cognite Function. Limited to 100KB in size."
+    )
+
+
+class FunctionTaskParameters(BaseModelResource):
+    function: CogniteFunctionRef
+    is_async_complete: bool = Field(
+        False, description="Defines if the execution of the task should be completed asynchronously."
+    )
+
+
+class TransformationRef(BaseModelResource):
+    external_id: str = Field(
+        description="The external id of the Transformation in the project. This can be either a transformation external ID or a reference like ${myTaskExternalId.output.someKey}"
+    )
+    concurrency_policy: Literal["fail", "waitForCurrent", "restartAfterCurrent"] = Field(
+        "fail",
+        description="""Determines the behavior of the task if the Transformation is already running.
+
+fail: The task fails if another instance of the Transformation is currently running.
+waitForCurrent: The task will pause and wait for the already running Transformation to complete. Once completed, the task is completed. This mode is useful for preventing redundant Transformation runs.
+restartAfterCurrent: The task waits for the ongoing Transformation to finish. After completion, the task restarts the Transformation. This mode ensures that the most recent data can be used by following tasks.""",
+    )
+    use_transformation_credentials: bool = Field(
+        False,
+        description="If set to true, the transformation will run using the client credentials configured on the transformation. If set to false, the transformation will run using the client credentials used to trigger the workflow.",
+    )
+
+
+class TransformationTaskParameters(BaseModelResource):
+    transformation: TransformationRef
+
+
+class CDFRequest(BaseModelResource):
+    resource_path: str = Field(
+        description="The path of the request. The path should be prefixed by {cluster}.cognitedata.com/api/v1/project/{project} based on the relevant cluster and project. It can also contain references like ${myTaskExternalId.output.someKey}"
+    )
+    method: Literal["POST", "GET", "PUT"] | str = Field(
+        description="The HTTP method of the request. It can also be a reference like ${myTaskExternalId.output.someKey}"
+    )
+    query_parameters: dict[str, JsonValue] | str | None = Field(
+        None,
+        description="The query parameters of the request. It can also be a reference like ${myTaskExternalId.output.someKey}",
+    )
+    body: JsonValue | str | None = Field(
+        None, description="The body of the request. It can also be a reference like ${myTaskExternalId.output.someKey}"
+    )
+    request_timeout_in_millis: float | str | None = Field(
+        None,
+        description="The timeout for the request in milliseconds. It can also be a reference like ${myTaskExternalId.output.someKey}",
+    )
+    cdf_version_header: Literal["alpha", "beta"] | str | None = Field(
+        None, description="The Cognite Data Fusion version header to use for the request."
+    )
+
+
+class CDFTaskParameters(BaseModelResource):
+    cdf_request: CDFRequest
+
+
+class DynamicRef(BaseModelResource):
+    tasks: str = Field(
+        description="A Reference is an expression that allows dynamically injecting input to a task during execution. References can be used to reference the input of the Workflow, the output of a previous task in the Workflow, or the input of a previous task in the Workflow. Note that the injected value must be valid in the context of the property it is injected into. Example Task reference: ${myTaskExternalId.output.someKey} Example Workflow input reference: ${workflow.input.myKey}"
+    )
+
+
+class DynamicTaskParameters(BaseModelResource):
+    dynamic: DynamicRef = Field(description="Reference to another task to use as the definition for this task.")
+
+
+class SubworkflowRef(BaseModelResource):
+    tasks: "WorkflowVersionId | list[Task]" = Field(
+        description="Reference to the subworkflow to execute. This can be either a reference to an existing workflow version or an inline definition of tasks."
+    )
+
+
+class SubworkflowTaskParameters(BaseModelResource):
+    subworkflow: SubworkflowRef = Field(description="Reference to the subworkflow to execute.")
+
+
+class SimulatorInputUnit(BaseModelResource):
+    name: str = Field(description="Name of the unit.")
+
+
+class SimulatorInput(BaseModelResource):
+    reference_id: str = Field(description="Reference id of the value to override.")
+    value: str | int | float | list[str] | list[int] | list[float] = Field(
+        description="Override the value used for a simulation run."
+    )
+    unit: SimulatorInputUnit | None = Field(None, description="Override the unit of the value")
+
+
+class SimulationRef(BaseModelResource):
+    routine_external_id: str = Field(description="The external id of the routine to be executed.")
+    run_time: int | None = Field(
+        None,
+        description="Run time in milliseconds. Reference timestamp used for data pre-processing and data sampling.",
+    )
+    inputs: list[SimulatorInput] | None = Field(
+        None, description="List of inputs to be provided to the simulation.", max_length=200
+    )
+
+
+class SimulationTaskParameters(BaseModelResource):
+    simulation: SimulationRef = Field(description="Reference to the simulation to execute.")
+
+
+class TaskId(BaseModelResource):
+    external_id: str = Field(
+        max_length=255, description="The external ID provided by the client. Must be unique for the resource type."
+    )
+
+
+class TaskDefinition(BaseModelResource, ABC):
+    external_id: str = Field(
+        max_length=255,
+        description="Identifier for the task. Must be unique within the version. No trailing or leading whitespace and no null characters allowed.",
+    )
+    type: str
+    name: str | None = Field(
+        default=None,
+        max_length=255,
+        description="Readable name meant for use in UIs",
+    )
+    description: str | None = Field(
+        default=None,
+        max_length=500,
+        description="Description of the intention of the task",
+    )
+    retries: int = Field(
+        3,
+        ge=0,
+        le=10,
+        description="Number of times to retry the task if it fails. If set to 0, the task will not be retried. The behavior for timeouts and retries is defined by the onFailure parameter, refer to it for more information.",
+    )
+    timeout: int = Field(
+        3600,
+        ge=60,
+        le=86400,
+        description="TTimeout in seconds. After this time, the task will be marked as TIMED_OUT. By default, the task won't be retried upon timeout. Use the onFailure parameter to change this behavior.",
+    )
+    on_failure: Literal["abortWorkflow", "skipTask"] = Field(
+        "abortWorkflow",
+        description="Defines the behavior when a task fails. If set to abortWorkflow, the entire workflow will be marked as FAILED when the task fails. If set to skipTask, the task will be marked as FAILED, but the workflow will continue executing subsequent tasks that are not dependent on the failed task.",
+    )
+    depends_on: list[TaskId] | None = Field(
+        None,
+        description="The tasks that must be completed before this task can be executed.",
+        max_length=100,
+    )
+
+
+class FunctionTask(TaskDefinition):
+    type: Literal["function"] = "function"
+    parameters: FunctionTaskParameters
+
+
+class TransformationTask(TaskDefinition):
+    type: Literal["transformation"] = "transformation"
+    parameters: TransformationTaskParameters
+
+
+class CDFTask(TaskDefinition):
+    type: Literal["cdfRequest"] = "cdfRequest"
+    parameters: CDFTaskParameters
+
+
+class DynamicTask(TaskDefinition):
+    type: Literal["dynamic"] = "dynamic"
+    parameters: DynamicTaskParameters
+
+
+class SubworkflowTask(TaskDefinition):
+    type: Literal["subworkflow"] = "subworkflow"
+    parameters: SubworkflowTaskParameters
+
+
+class SimulationTask(TaskDefinition):
+    type: Literal["simulation"] = "simulation"
+    parameters: SimulationTaskParameters
+
+
+Task = Annotated[
+    FunctionTask | TransformationTask | CDFTask | DynamicTask | SubworkflowTask | SimulationTask,
+    Field(discriminator="type"),
+]
+
+
+class WorkflowDefinition(BaseModelResource):
+    description: str | None = Field(
+        default=None,
+        max_length=500,
+        description="The description of the workflow version.",
+    )
+    tasks: list[Task]
+
+
+class WorkflowVersionYAML(ToolkitResource):
+    _cdf_resource = WorkflowVersionUpsert
+    workflow_external_id: str = Field(
+        max_length=255,
+        description="Identifier for a workflow. Must be unique for the project. No trailing or leading whitespace and no null characters allowed.",
+    )
+    version: str = Field(
+        max_length=255,
+        description="Identifier for a version. Must be unique for the workflow. No trailing or leading whitespace and no null characters allowed.",
+    )
+    workflow_definition: WorkflowDefinition

cognite_toolkit/_cdf_tk/storageio/__init__.py

@@ -0,0 +1,69 @@
+from cognite_toolkit._cdf_tk.utils._auxiliary import get_concrete_subclasses
+
+from ._annotations import AnnotationIO
+from ._applications import CanvasIO, ChartIO
+from ._asset_centric import (
+    AssetCentricIO,
+    AssetIO,
+    EventIO,
+    FileMetadataIO,
+    HierarchyIO,
+    TimeSeriesIO,
+)
+from ._base import (
+    ConfigurableStorageIO,
+    Page,
+    StorageIO,
+    StorageIOConfig,
+    T_Selector,
+    TableStorageIO,
+    UploadableStorageIO,
+    UploadItem,
+)
+from ._data_classes import InstanceIdCSVList, InstanceIdRow, ModelList
+from ._datapoints import DatapointsIO
+from ._file_content import FileContentIO
+from ._instances import InstanceIO
+from ._raw import RawIO
+from .selectors._base import DataSelector
+
+# MyPy fails to recognize that get_concrete_subclasses always returns a list of concrete subclasses.
+STORAGE_IO_CLASSES = get_concrete_subclasses(StorageIO)  # type: ignore[type-abstract]
+UPLOAD_IO_CLASSES = get_concrete_subclasses(UploadableStorageIO)  # type: ignore[type-abstract]
+
+
+def get_upload_io(selector: DataSelector) -> type[UploadableStorageIO]:
+    """Get the appropriate UploadableStorageIO class based on the type of the provided selector."""
+    for cls in UPLOAD_IO_CLASSES:
+        if isinstance(selector, cls.BASE_SELECTOR) and selector.kind == cls.KIND:
+            return cls
+    raise ValueError(f"No UploadableStorageIO found for selector of type {type(selector).__name__}")
+
+
+__all__ = [
+    "AnnotationIO",
+    "AssetCentricIO",
+    "AssetIO",
+    "CanvasIO",
+    "ChartIO",
+    "ConfigurableStorageIO",
+    "DatapointsIO",
+    "EventIO",
+    "FileContentIO",
+    "FileMetadataIO",
+    "HierarchyIO",
+    "InstanceIO",
+    "InstanceIdCSVList",
+    "InstanceIdRow",
+    "ModelList",
+    "Page",
+    "RawIO",
+    "StorageIO",
+    "StorageIOConfig",
+    "T_Selector",
+    "TableStorageIO",
+    "TimeSeriesIO",
+    "UploadItem",
+    "UploadableStorageIO",
+    "get_upload_io",
+]

cognite_toolkit/_cdf_tk/storageio/_annotations.py

@@ -0,0 +1,105 @@
+from collections.abc import Iterable, Sequence
+from typing import Any
+
+from cognite.client.data_classes import Annotation, AnnotationFilter
+
+from cognite_toolkit._cdf_tk.utils.collection import chunker_sequence
+from cognite_toolkit._cdf_tk.utils.useful_types import JsonVal
+
+from ._asset_centric import FileMetadataIO
+from ._base import Page, StorageIO
+from .selectors import AssetCentricSelector
+
+
+class AnnotationIO(StorageIO[AssetCentricSelector, Annotation]):
+    SUPPORTED_DOWNLOAD_FORMATS = frozenset({".ndjson"})
+    SUPPORTED_COMPRESSIONS = frozenset({".gz"})
+    CHUNK_SIZE = 1000
+    BASE_SELECTOR = AssetCentricSelector
+
+    MISSING_ID = "<MISSING_RESOURCE_ID>"
+
+    def as_id(self, item: Annotation) -> str:
+        project = item._cognite_client.config.project
+        return f"INTERNAL_ID_project_{project}_{item.id!s}"
+
+    def stream_data(self, selector: AssetCentricSelector, limit: int | None = None) -> Iterable[Page[Annotation]]:
+        total = 0
+        for file_chunk in FileMetadataIO(self.client).stream_data(selector, None):
+            for annotation_type in ["diagrams.AssetLink", "diagrams.FileLink"]:
+                # Todo Support pagination. This is missing in the SDK.
+                results = self.client.annotations.list(
+                    filter=AnnotationFilter(
+                        annotated_resource_type="file",
+                        annotated_resource_ids=[{"id": file_metadata.id} for file_metadata in file_chunk.items],
+                        annotation_type=annotation_type,
+                    ),
+                    limit=-1,
+                )
+                if limit is not None and total + len(results) > limit:
+                    results = results[: limit - total]
+
+                for chunk in chunker_sequence(results, self.CHUNK_SIZE):
+                    yield Page(worker_id="main", items=chunk)
+                    total += len(chunk)
+                if limit is not None and total >= limit:
+                    break
+
+    def count(self, selector: AssetCentricSelector) -> int | None:
+        """There is no efficient way to count annotations in CDF."""
+        return None
+
+    def data_to_json_chunk(
+        self, data_chunk: Sequence[Annotation], selector: AssetCentricSelector | None = None
+    ) -> list[dict[str, JsonVal]]:
+        files_ids: set[int] = set()
+        for item in data_chunk:
+            if item.annotated_resource_type == "file" and item.annotated_resource_id is not None:
+                files_ids.add(item.annotated_resource_id)
+            if file_id := self._get_file_id(item.data):
+                files_ids.add(file_id)
+        self.client.lookup.files.external_id(list(files_ids))  # Preload file external IDs
+        asset_ids = {asset_id for item in data_chunk if (asset_id := self._get_asset_id(item.data))}
+        self.client.lookup.assets.external_id(list(asset_ids))  # Preload asset external IDs
+        return [self.dump_annotation_to_json(item) for item in data_chunk]
+
+    def dump_annotation_to_json(self, annotation: Annotation) -> dict[str, JsonVal]:
+        """Dump annotations to a list of JSON serializable dictionaries.
+
+        Args:
+            annotation: The annotations to dump.
+
+        Returns:
+            A list of JSON serializable dictionaries representing the annotations.
+        """
+        dumped = annotation.as_write().dump()
+        if isinstance(annotated_resource_id := dumped.pop("annotatedResourceId", None), int):
+            external_id = self.client.lookup.files.external_id(annotated_resource_id)
+            dumped["annotatedResourceExternalId"] = self.MISSING_ID if external_id is None else external_id
+
+        if isinstance(data := dumped.get("data"), dict):
+            if isinstance(file_ref := data.get("fileRef"), dict) and isinstance(file_ref.get("id"), int):
+                external_id = self.client.lookup.files.external_id(file_ref.pop("id"))
+                file_ref["externalId"] = self.MISSING_ID if external_id is None else external_id
+            if isinstance(asset_ref := data.get("assetRef"), dict) and isinstance(asset_ref.get("id"), int):
+                external_id = self.client.lookup.assets.external_id(asset_ref.pop("id"))
+                asset_ref["externalId"] = self.MISSING_ID if external_id is None else external_id
+        return dumped
+
+    @classmethod
+    def _get_file_id(cls, data: dict[str, Any]) -> int | None:
+        file_ref = data.get("fileRef")
+        if isinstance(file_ref, dict):
+            id_ = file_ref.get("id")
+            if isinstance(id_, int):
+                return id_
+        return None
+
+    @classmethod
+    def _get_asset_id(cls, data: dict[str, Any]) -> int | None:
+        asset_ref = data.get("assetRef")
+        if isinstance(asset_ref, dict):
+            id_ = asset_ref.get("id")
+            if isinstance(id_, int):
+                return id_
+        return None