File Annotation reference

The File Annotation deployment pack (dp:contextualization:cdf_file_annotation) annotates P&IDs, drawings, and other documents in Cognite Data Fusion (CDF) with Diagram Detect and pattern mode, and links them to the assets and files they mention. It deploys as a module for the Cognite Toolkit. A data workflow calls one function in Cognite Functions, fn_file_annotation, four times, once per stage: prepare, launch, finalize, and promote. A transformation then links annotated files to assets. Progress per file is tracked on the FileAnnotationState view, and results are written to CDF RAW for reporting.

File Annotation is a cherry-pickable module inside the Contextualization deployment pack (dp:contextualization). You can add it on its own or alongside the other contextualization modules.

Who it’s for

Data engineers deploy and tune the pipeline. Subject matter experts review suggested annotations. Use this pack when you want a configuration-driven pipeline that:

Annotates documents against assets and files in your data model.
Combines regular Diagram Detect with pattern-mode detection and automatic promotion of pattern hits.
Handles large volumes, multi-page files, site and unit scoping, and several instance spaces.

Use something else when:

You need to match time series to assets. Use CDF Entity Matching.
You need to populate aliases. This pack doesn’t write them. Use the aliases update function in CDF Entity Matching. See One aliases function per project.

What’s included

Component	Description
Function `fn_file_annotation`	One function with four stages, selected by the `stage` input.
Data workflow `wf_ctx_file_annotation`	Runs prepare, launch, finalize, promote, then `tr_file_to_asset_from_annotations`. Each task retries once.
Scheduled trigger	The default `workflowSchedule` (`0 0 29 2 *`) only fires on 29 February. Start runs manually or set a schedule.
Extraction pipeline `ep_ctx_file_annotation`	Views, thresholds, tags, and scope settings that the function reads.
Helper data model	The `FileAnnotationState` view in `dm_file_annotation`, and a sink node that stores unresolved pattern hits until promote matches them.
Transformations	`tr_file_to_asset_from_annotations` (in the workflow), plus optional tag helpers and a status report. See Transformations.
RAW database `raw_file_annotation`	Annotation results, caches, the manual pattern catalog, and the status report. See Results and reporting.
Access group and data set	`producer_pp_file_annotation_<environment>` and `ds_file_annotation`.
Streamlit dashboards	File annotation quality and File annotation pipeline health (optional).
`upload_data/`	A sample manual pattern catalog (optional).

Prerequisites

The Cognite Toolkit version 0.8 or later is installed, and cdf.toml exists in your project root. See Setting up.
Authentication is configured with cdf auth init and cdf auth verify. See Authentication and authorization.
Files and assets are ingested, with aliases populated by the aliases update function from CDF Entity Matching. Diagram Detect matches on aliases.
You have an identity provider (IdP) application (IDP_CLIENT_ID, IDP_CLIENT_SECRET) and the source ID of an IdP group (GROUP_SOURCE_ID).
To upload the sample pattern catalog, the data plugin is enabled in cdf.toml:
[plugins] data = true

Install and deploy

Add to an existing project
Start a new project

cdf modules add -d contextualization:cdf_file_annotation

In an empty directory, run cdf modules init ..
Choose Contextualization, select Contextualization File Annotation with Space, and press Enter.

In config.<env>.yaml, set at minimum:

The file and target entity views and instance spaces. The defaults point to CogniteFile and CogniteAsset in sp_cdm_instances.
functionClientId, functionClientSecret, and groupSourceId.
ApplicationOwner, which the Streamlit apps require, and environment, which is used in the group name.

Then build and deploy:

Build deployment artifacts

cdf build

The Toolkit substitutes template variables and writes artifacts to the build/ directory. If you need to change the project name or any variables marked <change_me>, edit config.<env>.yaml first — see Configure, build, and deploy modules.

Dry-run the deployment

cdf deploy --dry-run

Inspect the output and confirm that configurations look correct before deploying.

Deploy to CDF

cdf deploy

The Toolkit deploys only configurations that have changed since the last run.

Set up CI/CD (optional)

For governed production deployments, automate build, dry-run, and deploy in a pipeline. See Set up CI/CD pipelines.

If you previously deployed separate prepare, launch, finalize, and promote functions, use the build output from that deployment to preview the cleanup:

cdf clean --dry-run

The cdf clean command deletes every resource managed by the configurations in the build, not only the four legacy functions. Review the dry-run output and continue only if you can safely delete every listed resource. Then run cdf clean, rebuild, and deploy the current module. Custom callers must now pass stage to fn_file_annotation.

Review the dry-run output before you run cdf clean. The command deletes every resource managed by that build.

Optional: tag test data. If your instances aren’t tagged yet, run the tag helpers once. They add tags without overwriting existing ones, and they don’t set aliases:

cdf transformations run tr_tag_assets_detect_in_diagrams
cdf transformations run tr_tag_files_detect_in_diagrams
cdf transformations run tr_tag_files_to_annotate

Optional: upload the sample pattern catalog:

cdf data upload dir modules/contextualization/cdf_file_annotation/upload_data

Verify the deployment

cdf deploy finishes without errors.
Tag at least one file ToAnnotate and its assets DetectInDiagrams.
In Integrate > Data Workflows, run wf_ctx_file_annotation and confirm that all five tasks succeed.
In Integrate > Staging (RAW), confirm that raw_file_annotation.annotation_documents_tags has rows.
Open the annotated file in CDF Search and confirm the annotations are visible.

How it works

Stage	What it does
Prepare	Selects files tagged `ToAnnotate` and not excluded, and creates a `FileAnnotationState` with status `New`.
Launch	Groups files by scope, loads the `DetectInDiagrams` entities for each scope, and submits a regular Diagram Detect job. When `patternMode` is `true`, also submits a pattern-mode job.
Finalize	Applies confidence thresholds to regular hits: at or above approval is Approved, at or above suggest is Suggested, and anything lower is dropped. Pattern hits in new regions become Suggested annotations on a sink node. Writes annotations and RAW rows.
Promote	Resolves pattern hits by looking up the detected text in `aliases`. One match is Approved and tagged `PromotedAuto`. No match is Rejected and tagged `PromoteAttempted`. Several matches stay Suggested and are tagged `AmbiguousMatch`.
Link assets	`tr_file_to_asset_from_annotations` sets `assets` on each file from its approved annotations.

Large documents are processed in 50-page chunks. Finalize uses optimistic locking, so concurrent finalize tasks do not overwrite one another’s updates. You can add more finalize tasks to the workflow (same function, stage: finalize) to increase throughput.

Tags and aliases

Tags decide which instances the pipeline processes. They’re never matched against diagram text. Aliases are the strings that Diagram Detect and promote look for.

Tag	Used on	Effect
`ToAnnotate`	Files	Prepare picks up the file.
`DetectInDiagrams`	Assets and files	Launch includes the instance as a match candidate.
`ScopeWideDetect`	Assets and files	The instance is a candidate in every secondary scope within its primary scope.
`AnnotationInProcess`, `Annotated`, `AnnotationFailed`	Files	Set by the pipeline. Excluded by prepare by default.

To reprocess finished files, add Annotated or AnnotationFailed to filesToAnnotateTags. They’re then removed from the exclude list automatically.

One aliases function per project

Use one aliases function for the whole project: fn_dm_context_aliases_update from the CDF Entity Matching module. It writes aliases on time series, assets, and files, so entity matching and file annotation match on the same strings. Don’t run a second alias pipeline for file annotation. Two pipelines with different patterns write conflicting aliases, and matches then succeed in one module and fail in the other. The aliases update function joins tag parts with -, so the name VAL_23-KA-9101 gets the alias 23-KA-9101. Earlier versions wrote 23_KA_9101. Keep these settings coordinated when you change either module:

Entity Matching setting	File Annotation setting	Keep aligned so that
`assetAliasPattern`	`entityNormalizationPatterns`	Promote extracts the same asset tag forms that the aliases contain.
`fileAliasPattern`	`fileNormalizationPatterns`	Promote extracts the same document numbers that file aliases contain.
`fileView` in `ep_ctx_aliases_update`	File view variables	Aliases are written on the files you annotate.
Instance space variables	`fileInstanceSpace`, `targetEntityInstanceSpace`	Both modules read and write the same instances.

Run the aliases update before the file annotation workflow whenever names change, so launch and promote see current aliases.

Configuration reference

Set these variables in config.<env>.yaml before running cdf build. Required variables must be set for your project. Optional variables can keep their defaults. Diagram Detect limits, batch sizes, and RAW table names are fixed in functions/fn_file_annotation/fa_constants.py. Edit that file and redeploy to change them.

Views and spaces

Variable	Type	Required	Description	Default
`fileSchemaSpace`, `fileExternalId`, `fileVersion`	string	Optional	File view.	`cdf_cdm`, `CogniteFile`, `v1`
`fileInstanceSpace`	string	Optional	Space for files. Empty means every space. See Multiple instance spaces.	`sp_cdm_instances`
`targetEntitySchemaSpace`, `targetEntityExternalId`, `targetEntityVersion`	string	Optional	Target entity (asset) view.	`cdf_cdm`, `CogniteAsset`, `v1`
`targetEntityInstanceSpace`	string	Optional	Space for assets. Empty means the same space as each file.	`sp_cdm_instances`
`fileSearchProperty`, `targetEntitySearchProperty`	string	Optional	Property whose values are matched on drawings.	`aliases`
`fileResourceProperty`, `targetEntityResourceProperty`	string	Optional	Property used only to classify results, for example `equipmentType`. Not used for matching.	`""`

Matching

Variable	Type	Required	Description	Default
`assetAutoApprovalThreshold`, `assetAutoSuggestThreshold`	number	Optional	Confidence thresholds for asset links.	`0.85`, `0.7`
`fileAutoApprovalThreshold`, `fileAutoSuggestThreshold`	number	Optional	Confidence thresholds for file links.	`0.50`, `0.30`
`patternMode`	boolean	Optional	Run pattern-mode detection alongside regular detection.	`true`
`structuralAutoPatterns`	boolean	Optional	Generate shape samples such as `00-AA-0000` from aliases.	`true`
`entityNormalizationPatterns`, `fileNormalizationPatterns`	list of strings	Optional	Regex lists that extract tag forms for promote and pattern samples. See Text normalization.	Tag and document number patterns
`cleanOldAnnotations`	boolean	Optional	Delete annotations created by earlier runs before re-annotating. Manual annotations are kept.	`false`
`debugFileExternalId`	string	Optional	Process only this file, ignoring tags. Requires `fileInstanceSpace`.	`""`

After changing thresholds, run once with cleanOldAnnotations: true so annotations from earlier runs are replaced.

Variable	Type	Required	Description	Default
`filesToAnnotateTags`	list of strings	Optional	Files prepare picks up.	`ToAnnotate`
`filesToAnnotateExcludeTags`	list of strings	Optional	Files prepare skips.	`AnnotationInProcess`, `Annotated`, `AnnotationFailed`
`fileEntitiesTags`, `targetEntitiesTags`	list of strings	Optional	Files and assets used as match candidates.	`DetectInDiagrams`

Scope

Variable	Type	Required	Description	Default
`primaryScopeProperty`	string	Optional	Property name for the coarse boundary, for example `site`.	`""`
`secondaryScopeProperty`	string	Optional	Property name for the finer boundary, for example `unit`.	`""`
`filterPatternPromoteByScope`	boolean	Optional	Make promote use the same scope as launch.	`true`

Without scope, every file is matched against all tagged entities. The same tag text often exists on several sites, which causes false positives, and large projects can exceed the Diagram Detect limit of 500,000 entities per call. With scope set, launch batches files by their scope values and only includes entities with the same values, plus ScopeWideDetect entities in the same primary scope. The property must be a text property with the same name on the file view and the target entity view. The core CogniteFile and CogniteAsset views don’t have one, so use views that extend them. For a file with site=PlantA and unit=U100:

Asset	`site`	`unit`	Tags	Candidate?
`23-KA-9101`	PlantA	U100	`DetectInDiagrams`	Yes
`PA-FLARE-01`	PlantA	U300	`DetectInDiagrams`, `ScopeWideDetect`	Yes
`23-KA-9102`	PlantA	U300	`DetectInDiagrams`	No, different unit
`45-PB-2001`	PlantB	U200	`DetectInDiagrams`	No, different site

Files and assets without a primary scope value are still matched, against everything, and launch logs a warning. Set the scope values on every file and asset you annotate.

Multiple instance spaces

Leave fileInstanceSpace and targetEntityInstanceSpace empty ("") when each site keeps its files and assets in its own space. Prepare then picks up files from every space. Each file is matched only against entities in its own space, and annotations and state are stored next to the file. You can also set one and leave the other empty, for example one shared asset space with files in many spaces. With an empty space, the transformations and debugFileExternalId don’t work, because they need a single space. The access group needs read and write on every space you annotate.

Text normalization

Promote uses entityNormalizationPatterns (assets) and fileNormalizationPatterns (files) to extract tag forms from detected text before searching aliases. Use the same patterns as the alias patterns in the aliases update function, so promote looks for the forms your aliases contain. See One aliases function per project. When several patterns match, the longest form wins. An empty list turns normalization off for that source. Lookups are case-sensitive exact matches. In the current version, promote builds its search forms by joining capture groups with _, plus the detected text as written and a form with separators removed. It doesn’t generate the - form that the aliases update function now writes. A tag detected inside longer text, such as VAL_23-KA-9101, can therefore be rejected even though the alias 23-KA-9101 exists. Check annotation_documents_patterns for rejected tags that exist as assets.

A tag detected inside longer text can be rejected even when the matching alias exists. Promote doesn’t generate the - form that the aliases update function writes.

entityNormalizationPatterns:
  - '([0-9]{2}[-_.:][A-Z]{2,4}[-_.:][0-9]{4,5})'
fileNormalizationPatterns: []

Write character classes such as [0-9], not \d. The Cognite Toolkit rejects backslash escapes in variables. A pattern without a capture group fails when the config loads.

Data workflow and access

The variables in this table belong in config.<env>.yaml, except logLevel, which is set on each workflow task.

Variable	Type	Required	Description	Default
`workflowExternalId`, `workflowSchedule`	string	Optional	Workflow ID and cron schedule.	`wf_ctx_file_annotation`, `0 0 29 2 *`
`functionExternalId`, `functionVersion`, `functionSpace`	string	Optional	Function and the space for its code.	`fn_file_annotation`, `v1.0.0`, `inst_file_annotation_function`
`functionClientId`, `functionClientSecret`	string	Required	Credentials for the function and trigger.	`${IDP_CLIENT_ID}`, `${IDP_CLIENT_SECRET}`
`groupSourceId`	string	Required	IdP group source ID.	`${GROUP_SOURCE_ID}`
`environment`	string	Optional	Suffix of the group name.	`dev`
`ApplicationOwner`	string	Required	Owner email for the Streamlit apps.	`<APPLICATION_OWNER>`
`extractionPipelineExternalId`, `annotationDatasetExternalId`	string	Optional	Extraction pipeline and data set.	`ep_ctx_file_annotation`, `ds_file_annotation`
`logLevel`	string	Optional	Logging level for a workflow task: `DEBUG`, `INFO`, `WARNING`, or `ERROR`.	`INFO`

Results and reporting

Results are written to the RAW database raw_file_annotation.

Table	Contents
`annotation_documents_tags`	Asset links from regular detection.
`annotation_documents_docs`	File-to-file links.
`annotation_documents_patterns`	Pattern hits and their promote outcome: `Suggested`, `Approved`, or `Rejected`.
`annotation_file_status_report`	Per-file matched and unmatched tags, written by `tr_file_annotation_status_report`.
`annotation_entities_cache`, `annotation_tags_cache`	Entity and promote caches.
`manual_patterns_catalog`	Manual pattern overrides, looked up for `GLOBAL`, then site, then site and unit.

To find tags that are on a drawing but not in your asset hierarchy, query annotation_documents_patterns for status = Rejected, or run the status report after promote. Text that Diagram Detect never associates with an entity or pattern isn’t stored.

Transformations

Transformation	Purpose	In workflow?
`tr_file_to_asset_from_annotations`	Sets `assets` on files from approved annotations.	Yes
`tr_file_annotation_status_report`	Writes the per-file report. Run it after promote.	No
`tr_tag_assets_detect_in_diagrams`, `tr_tag_files_detect_in_diagrams`, `tr_tag_files_to_annotate`	Add `DetectInDiagrams` or `ToAnnotate` tags for testing.	No

Troubleshooting

No files are picked up

Check that the files are tagged ToAnnotate and don’t carry an exclude tag such as Annotated. To reprocess annotated files, add Annotated or AnnotationFailed to filesToAnnotateTags.

Files fail with No entities or pattern samples found

Launch found no candidates for the file’s scope. Tag assets and reference files DetectInDiagrams, populate aliases, and check that the scope values match. The pipeline tags the failed file AnnotationFailed, which prepare excludes. Add AnnotationFailed to filesToAnnotateTags. Prepare then removes that tag from the exclude list and creates a FileAnnotationState with status New. Run the workflow again.

Annotations link to assets on another site or unit

Set primaryScopeProperty (and optionally secondaryScopeProperty), populate the scope values on files and assets, and keep filterPatternPromoteByScope: true.

Diagram Detect fails with an entity length error

Too many entities in one call (limit 500,000). Set the scope properties, or split the data into separate instance spaces.

Promote rejects tags that exist as assets

The normalized text doesn’t match any alias exactly. Check that one aliases function writes the aliases for the project, and that entityNormalizationPatterns match its assetAliasPattern. If the aliases use - and the tag was detected inside longer text, see Text normalization.

Too few approved annotations

Lower the assetAuto* or fileAuto* thresholds, then run once with cleanOldAnnotations: true.

The status report or tag helpers update no rows

Check the view and instance space variables, and rebuild with cdf build. These transformations need a single instance space, so they don’t work when the space variables are empty.

The workflow fails with an access error

Verify functionClientId, functionClientSecret, and groupSourceId, and that the group has access to every instance space you annotate. See Access management.

For more detail, set logLevel to DEBUG on the workflow task. See Data workflow and access. For issues not covered here, contact Cognite support.

Support

Field	Details
Team	Cognite Value Delivery Team
Documentation	Cognite product documentation
Questions and feedback	Deployment Packs group on Cognite Hub
Version	1.0.0
Last updated	2026

Configure and deploy

File Annotation reference

Who it’s for

What’s included

Prerequisites

Install and deploy

Verify the deployment

How it works

Tags and aliases

One aliases function per project

Configuration reference

Views and spaces

Matching

Tags

Scope

Multiple instance spaces

Text normalization

Data workflow and access

Results and reporting

Transformations

Troubleshooting

Further reading

Support

​Who it’s for

​What’s included

​Prerequisites

​Install and deploy

​Verify the deployment

​How it works

​Tags and aliases

​One aliases function per project

​Configuration reference

​Views and spaces

​Matching

​Tags

​Scope

​Multiple instance spaces

​Text normalization

​Data workflow and access

​Results and reporting

​Transformations

​Troubleshooting

​Further reading

​Support

Who it’s for

What’s included

Prerequisites

Install and deploy

Verify the deployment

How it works

Tags and aliases

One aliases function per project

Configuration reference

Views and spaces

Matching

Tags

Scope

Multiple instance spaces

Text normalization

Data workflow and access

Results and reporting

Transformations

Troubleshooting

Further reading

Support