Configure InField on CDM

The features described in this section are in public preview and may change.

This article helps you configure the source data and Cognite Data Fusion (CDF) project that powers Cognite InField (InField), and describes how to set up assets and visualize data. You can also deploy InField with pre-built configurations using the Cognite Toolkit.

For legacy APM configuration documentation, see the legacy configuration guide.

Before you start

Make sure you have the following:

A project registered in the CDF application. It must be a Data Modeling only project.
The CDF API and the CDF application registered in Microsoft Entra ID and Microsoft Entra ID and CDF groups set up to control access to CDF data.
Assets in the CDF project populated in the CogniteAsset concept.
URLs in your allowlist.
The Cognite Toolkit installed and configured. All location configuration and deployments in this guide use the Cognite Toolkit.

CDF and InField use different location concepts. Make sure to deploy locations for InField using the InField Quickstart deployment pack even if you already have locations set up in CDF.

Enable Core Data Model (CDM) mode

To enable CDM mode for your project:

Create the access group

Create a CDF group named exactly infield-on-cdm-access and add the users who should have access.

Verify access

Users in the infield-on-cdm-access group see the CDM version of InField when they open the application.

For a full project-wide rollout, contact your Cognite representative to enable CDM mode for all users in the project.

How CDM configuration works

InField CDM configuration is stored as a Data Modeling Service (DMS) node in CDF. Each location you configure in InField is a separate node instance of the InFieldCDMLocationConfig view in the cdf_infield space, part of the InFieldOnCDM data model. The collection of all node instances forms the list of configured locations. Each configuration node has the following top-level fields:

Field	Type	Required	Description
`space`	string	Yes	The DMS space this node instance lives in
`name`	string	No	Display name shown in the location picker
`description`	string	No	Human-readable description of the location
`dataStorage`	object	Yes	Identifies where the location’s data lives in CDF
`viewMappings`	object	No	Maps InField entity types to specific data modeling views
`featureToggles`	object	No	Enables or disables major app features for this location
`dataExplorationConfig`	object	No	Controls the Activities and Notifications asset exploration cards. The Properties card is configured separately via the top-level `assetPropertiesCardConfig` field.
`accessManagement`	object	No	CDF group names for admin roles
`disciplines`	array	No	List of disciplines surfaced during onboarding and in the UI
`dataFilters`	object	No	DMS-based scoping filters per resource type

Deploy all locations using the InField Quickstart deployment pack in the Cognite Toolkit.

Set up access

You can use your existing identity provider (IdP) framework to manage access to InField and choose admin users. We support Microsoft Entra ID. For the required group names and capabilities, see Configure InField in the capabilities reference. Use the following name suggestions when creating user groups. Access is based on the group name, so you can create similar groups for different locations. Group names can differ from user to user, but the location and env placeholders are recommended for multi-site deployments.

Name	Description
`infield_dev_location_viewers`	Users can view but not edit checklists in the specified location (`location`) and environment (`dev`).
`infield_dev_location_checklist_admins`	Users can create, update, delete, and approve checklists. Add this group name to `accessManagement.checklistAdmins[]` in the location config.
`infield_dev_location_template_admins`	Users can create, update, and delete templates. Add this group name to `accessManagement.templateAdmins[]` in the location config.
`infield_dev_location_checklist_users`	Users can work with checklists and create observations.

Create data modeling spaces

InField stores asset data in data models. You need to create at least three spaces to store your data and data models.

APM_Config is a legacy APM space and is not required for data modeling only projects on CDM. If you are migrating from APM, see the legacy configuration guide.

Space name	Description
`cognite_app_data`	This space holds user data, such as user profiles.
`yourRootLocation_source_data`	This space holds data from your source systems (like SAP) for one root location. Replace `yourRootLocation` with the name of your root location/asset.
`yourRootLocation_app_data`	This space holds data created in InField (like checklists and templates) for one root location. Replace `yourRootLocation` with the name of your root location/asset.
`ApmAppData`	You don’t need to set up or change this space. `ApmAppData` is a system data model that’s present in all projects by default. The data model has the `System` tag.
`cdf_infield`	You don’t need to set up or change this space. It contains the `InFieldOnCDM` system data model, which defines the InField configuration and observation schemas.

Create a unique pair of _source_data and _app_data spaces for each root location you want to configure in InField. For example, if you have two root locations named plant-a and plant-b, you will need to create four spaces in total:

plant-a_source_data
plant-a_app_data
plant-b_source_data
plant-b_app_data

You can create spaces with the Cognite Python SDK or the Cognite API. After you create them, confirm the spaces appear under the Data Fusion workspace > Data models > Spaces in CDF.

Python SDK
API

You can create the spaces using the Cognite Python SDK. Use the following Python code and replace yourRootLocation with your root location/asset name in yourRootLocation_source_data and yourRootLocation_app_data.

Create spaces

from cognite.client.data_classes.data_modeling import SpaceApply

# List of spaces to create
spaces_to_create = ["yourRootLocation_source_data", "yourRootLocation_app_data", "cognite_app_data"]

# Apply spaces
for space_name in spaces_to_create:
    client.data_modeling.spaces.apply(SpaceApply(space=space_name))

You can create the spaces using the API endpoint:

cognite_app_data
yourRootLocation_source_data
yourRootLocation_app_data

Use the same names for the space and name attributes. The space attribute is also the space ID. Replace yourRootLocation with your root location/asset name in yourRootLocation_source_data and yourRootLocation_app_data.

Prepare asset data

To display related data on the Asset explorer page, ensure data objects are connected to the corresponding assets in CDF. InField uses these relationships to find and display the relevant information for each asset.

Data object	Requirements
3D	The `CogniteAsset.object3D` property needs to have a 3D model linked to the asset in the `source_instance_space`.
Trends (time series)	The `CogniteTimeSeries.assets` property needs to have a direct relation to the asset in either the `app_instance_space` or `source_instance_space` of the current location.
Documents	The `CogniteFile.assets` property needs to have a direct relation to the asset in either the `app_instance_space` or `source_instance_space` of the current location. Supported document types in `CogniteFile.mimeType` include `text/plain`, `text/csv`, `application/json`, `application/pdf`, `image/svg+xml`.
Work orders	The `CogniteMaintenanceOrder.mainAsset` property needs to have a direct relation to the asset in the `source_instance_space` of the current location.
Notifications	The `CogniteNotification.asset` property needs to have a direct relation to the asset in the `source_instance_space` of the current location.
Properties	The `CogniteAsset` view needs to be extended with any custom properties you want to display for the asset.
Media	The `CogniteFile.assets` property needs to have a direct relation to the asset in either the `app_instance_space` or `source_instance_space`. Supported file types in `CogniteFile.mimeType` include `video/quicktime`, `video/mp4`, `image/jpeg`, `image/png`.

Make sure to contextualize files to the relevant asset to see them on the asset’s card.

Configure locations

Deploy locations using the InField Quickstart deployment pack in the Cognite Toolkit.

View mappings (`viewMappings`)

Views contain a group of properties that you can change for specific cases. By default, InField uses the Cognite process industries data model that extends the core data model to meet the needs of the process industries. You can customize entity definitions (or views), such as CogniteAsset and CogniteMaintenanceOrder, by extending them with properties that are specific to your operations. For example, to extend the CogniteMaintenanceOrder property, you can create a new view and add the Cost field. You can map logical entity types to views defined in the cdf_idm (Process industries data model), cdf_cdm (Core data model), or your custom view space. View mappings are configured in the viewMappings object of the InFieldCDMLocationConfig node. You can configure view mappings for seven entities. If you omit a mapping, InField uses the following default view for that entity.

Config key	Default view	Default space	Extendable
`asset`	`Asset`	`cdf_infield`	Yes
`maintenanceOrder`	`CogniteMaintenanceOrder`	`cdf_idm`	Yes
`operation`	`CogniteOperation`	`cdf_idm`	Yes
`notification`	`CogniteNotification`	`cdf_idm`	Yes
`file`	`CogniteFile`	`cdf_cdm`	Yes
`timeseries`	`InfieldTimeSeries`	`cdf_infield`	Yes
`observation`	`FieldObservation`	`cdf_infield`	Yes (array shape; see note below)

These defaults apply when a mapping is omitted. The InField Quickstart sets viewMappings.asset to cdf_cdm / CogniteAsset / v1 instead of the app fallback (cdf_infield / Asset).observation uses a different shape: an array of ObservationViewConfig objects rather than a single view reference. Only the first entry is supported. See Configure observations.

Make sure the view version always matches the data model version. Otherwise, the table on the Overview page won’t work correctly.

The operation, notification, and maintenanceOrder entity types have standard views defined in the cdf_idm system space. To view and customize these views, go to CDF > Data fusion > Data models > find and select CogniteProcessIndustries.

Data storage (`dataStorage`)

The dataStorage field identifies the root asset for the location and the space where InField writes app data.

dataStorage:
  rootLocation:
    space: yourRootLocation_source_data
    externalId: YOUR_ROOT_ASSET_EXTERNAL_ID
  appInstanceSpace: yourRootLocation_app_data

Sub-field	Description
`rootLocation.space`	The DMS space containing the root asset node
`rootLocation.externalId`	The external ID of the root asset node. This is the top-level asset in the hierarchy for this location. InField uses it as the anchor for navigation and scoping.
`appInstanceSpace`	The space where InField writes app-generated data, including checklists, templates, observations, and time series.

dataStorage.rootLocation is the instance ID of the root asset, not a data storage container. The spaces where source data (assets, work orders, notifications) is read from are configured separately in dataFilters.

Instance space scoping (`dataFilters`)

Use dataFilters to restrict InField queries to specific DMS spaces per resource type. Each resource type has an instanceSpaces[] array. Only some resource types support multiple spaces.

Example: dataFilters configuration

dataFilters:
  assets:
    instanceSpaces:
      - yourRootLocation_source_data
  files:
    instanceSpaces:
      - yourRootLocation_source_data
  timeseries:
    instanceSpaces:
      - yourRootLocation_source_data
  maintenanceOrders:
    instanceSpaces:
      - yourRootLocation_source_data
  operations:
    instanceSpaces:
      - yourRootLocation_source_data
  notifications:
    instanceSpaces:
      - yourRootLocation_source_data

Resource type	Config key	Multiple spaces
Assets	`dataFilters.assets.instanceSpaces[]`	No (1 space only)
Files	`dataFilters.files.instanceSpaces[]`	Yes
Time series	`dataFilters.timeseries.instanceSpaces[]`	Yes
Maintenance orders	`dataFilters.maintenanceOrders.instanceSpaces[]`	No (1 space only)
Operations	`dataFilters.operations.instanceSpaces[]`	No (1 space only)
Notifications	`dataFilters.notifications.instanceSpaces[]`	No (1 space only)

maintenanceOrders, operations, and notifications must all use the same instance space. Configuring different spaces for these three resource types will cause inconsistent results.

instanceSpaces is the only field consumed by InField today for every resource type under dataFilters.

Feature toggles (`featureToggles`)

Feature toggles let you enable or disable major app features for each location. All flags default to false if omitted, so only set the ones you want to turn on. Configure these in the featureToggles object of the location’s InFieldCDMLocationConfig node in the Cognite Toolkit.

Flag (`featureToggles.*`)	What it controls	Default
`threeD`	Shows the 3D viewer page and the 3D card on the asset overview	`false`
`trends`	Shows the trends and time series panel on the asset page	`false`
`documents`	Shows the documents tab and document cards	`false`
`workorders`	Enables the work orders and maintenance orders list and detail pages	`false`
`notifications`	Enables the notifications list and detail pages	`false`
`media`	Enables media (photo/video) attachments on checklists and observations	`false`
`templateChecklistFlow`	Enables template-based round checklists (created from templates)	`false`
`workorderChecklistFlow`	Enables work-order-linked checklists (created from a maintenance order)	`false`
`observations`	Enables the observations feature for field observations and defect logging	`false`
`schedules`	Enables the Schedules tab for managing recurring rounds	`false`
`copilot`	Enables the AI Copilot assistant panel	`false`

Admin roles (`accessManagement`)

Use accessManagement to define which CDF groups have admin access to checklists and templates for this location.

accessManagement:
  checklistAdmins:
    - infield-checklist-admin-group
  templateAdmins:
    - infield-template-admin-group

Field	Description
`checklistAdmins`	List of CDF group names whose members can create, update, delete, and approve checklists
`templateAdmins`	List of CDF group names whose members can create, update, and delete templates

These values must match the group names created in your identity provider. See Set up access for recommended naming conventions.

Disciplines (`disciplines`)

Use disciplines to define the list of disciplines available for selection during onboarding and elsewhere in the InField UI. Each entry has an externalId and a name.

disciplines:
  - externalId: mechanical
    name: Mechanical
  - externalId: electrical
    name: Electrical

Configure schedules

The Schedules tab lets supervisors create and manage recurring inspection rounds directly in InField. You do not need to deploy a CDF scheduling function to use the Schedules tab. If you want to trigger checklist creation automatically via a CDF function, you can set up a custom scheduling function. Contact your Cognite solution architect for an example.

The legacy APM scheduling function is not compatible with CDM. Remove the legacy APM scheduling function before deploying a CDM-compatible one. Reusing the legacy function will cause incorrect behavior with the CDM data model and the Schedules tab.

Configure observations

Observations allow field workers to report issues and track maintenance needs. The observation form is driven by a CDF view that renders the properties you define in that view. You can use the built-in default view or create a custom one.

Enable observations

In the Cognite Toolkit YAML for the location’s InFieldCDMLocationConfig node, set featureToggles.observations: true, then run cdf build and cdf deploy.

Choose the default or a custom view

Default view: Use the default view if the default fields are sufficient for your project: files, assets, observed time, name, description, troubleshooting steps, priority, type, and status. InField ships a built-in FieldObservation view in the cdf_infield space.

To use the default view, add the following to the viewMappings object of the location’s InFieldCDMLocationConfig node in the Cognite Toolkit:

viewMappings:
  observation:
    - view:
        space: cdf_infield
        externalId: FieldObservation
        version: v1

Custom view: Choose a custom view if you need different fields, custom enums, or SAP writeback.

Customize the view

Choose the fields and their types:

Field type	How it renders	Notes	How to make required
`String`	Text input	Single-line text.	Mark the property as non-nullable when creating the container in CDF. InField reads the schema and enforces the constraint in the form.
`Enum`	Dropdown	Enum types must be defined in the same space and version as the view. Dropdown options are sorted alphabetically by the enum key (ID). To control display order, use key prefixes with a sortable value, for example `m1_`, `m2_`, `m3_`.	Mark the property as non-nullable when creating the container in CDF.
`Timestamp`	Date/time picker	Stored as epoch ms; displayed in local time.	Mark the property as non-nullable when creating the container in CDF.
`Assets`	Search/select field	Direct relation to `CogniteAsset` or a view that extends it. Enables the asset hierarchy tree that opens from the root asset configured for the location.	Relations cannot be made non-nullable in CDF. To require an asset on the observation form, use `fieldsConfig.assets.isRequired: true` (preferred) or add `assets` to `requiredProperties`. Requires feature flag `INFIELD.observation_form_asset_field_required` (contact your Cognite representative).
`Files`	Drag-and-drop uploader	Direct relation to `CogniteFile`.	Relations cannot be made non-nullable in CDF. Use `fieldsConfig.files.isRequired: true` (preferred) or add `files` to `requiredProperties`.
Direct relation	Search field	Single direct relations only. Lists are not supported.	Not supported.

Rules and best practices:

Keep the form focused. Include only the fields users are expected to fill in.
Order properties intentionally. Use fieldsConfig.*.orderNumber in the view mapping to control the order fields appear in the form and table. orderNumber is the only supported way to guarantee field order.
Write clear field descriptions. They become placeholder text in the form.
Use clear property names. They become field labels.
Extend CogniteSourceable (and optionally CogniteActivity) to add standard metadata. These fields are autopopulated by the app and are not shown in the form.
Add indexes to any fields users will sort or filter on.
If SAP writeback is required, add sapStatus and notificationIdInSap fields to the view at this stage (see SAP writeback).

Create the container and view in CDF

Create the container. Create exactly one non-CDM container unique to this observation view. No two observation views may share the same non-CDM container, because this is how InField identifies which view to use for a given observation instance.
Create the view and enum types. Create the view referencing that container, and define any enum types in the same space and version as the view.
Optionally create a form view. Create a form view if you want to show only a subset of fields in the create/edit form while keeping all fields on the stored observation record. The form view must reuse the same containers as the main observation view. Do not create a new container for it.

Configure via the Cognite Toolkit

Add the observation mapping to viewMappings.observation[] in the location’s InFieldCDMLocationConfig. Always make this change through the Cognite Toolkit, as it validates view references before deployment.The full ObservationViewConfig supports:

Field	Required	Description
`view`	Yes	The main observation view reference (`space`, `externalId`, `version`)
`formView`	No	A subset view controlling which fields appear in the create/edit form
`fieldsConfig`	No	Per-field configuration: set `isRequired`, `isEditable`, and `orderNumber` for each property. Use the per-field configuration to control which fields are required, whether they are visible and editable in the form, and what order they appear. When `isEditable` is `false`, the field is hidden from the form entirely.
`requiredProperties`	No	A simpler alternative to `fieldsConfig.*.isRequired`. Lists property names that must be filled before submission. Use for `assets` and `files`.
`writeBack`	No	SAP writeback endpoint configuration

Example with all options:

Example: full ObservationViewConfig

viewMappings:
  observation:
    - view:
        space: customer_idm_extension
        externalId: FieldObservation
        version: v1
      formView:
        space: customer_idm_extension
        externalId: FieldObservationFormView
        version: v1
      fieldsConfig:
        name:
          isRequired: true
          isEditable: true
          orderNumber: 1
        description:
          isRequired: false
          isEditable: true
          orderNumber: 2
        asset:
          isRequired: true
          isEditable: true
          orderNumber: 3
        sourceId:
          isEditable: false
          orderNumber: 4
      writeBack:
        notificationsEndpointExternalId: sap-notifications-endpoint
        attachmentsEndpointExternalId: sap-attachments-endpoint

Only the first entry in viewMappings.observation[] is supported at this time.

Deploy and validate

Run the following commands in order:

cdf build
cdf deploy --dry-run
cdf deploy

Open InField and create a test observation. Verify:

All expected fields appear in the correct order.
Required fields block submission when empty.
Placeholder text shows correctly.
If SAP writeback is configured: submit a test observation and confirm sapStatus is set and notificationIdInSap is populated after a successful send.

When a user deletes an observation in the InField UI, it is permanently deleted and cannot be recovered.

SAP writeback

SAP writeback is only available to customers who have a SAP integration with a notifications endpoint deployed in CDF. You cannot use the default FieldObservation view for SAP writeback, because the required fields are not part of it. To enable SAP writeback:

Add the required fields to the custom observation view

Field	Type	Description
`sapStatus`	String enum	SAP send-status, separate from the business-level `status` field. Accepted values: `Sent`, `Not sent`, `File not sent`. Observations not yet sent to SAP should have no `sapStatus` set.
`notificationIdInSap`	String	SAP notification ID after a successful send.

Add the writeBack object to the observation mapping

Add the writeBack object to the observation mapping through the Cognite Toolkit. Use the structure in the Configure via the Cognite Toolkit step in Configure observations. The notification endpoint is required; the attachment endpoint is optional.

InField detects the presence of sapStatus and notificationIdInSap on the view and automatically enables the SAP writeback UI for field workers.

Observations are stored in the dataStorage.appInstanceSpace for the current location and can be queried using the data model APIs.

Configure asset explorer cards (`dataExplorationConfig`)

The dataExplorationConfig field is not yet finalized and may change.

You can customize what appears in the Properties, Activities, and Notifications cards on the asset page. The Properties card is configured via the top-level assetPropertiesCardConfig field; the Activities and Notifications cards are configured via dataExplorationConfig. Each card type is configured differently.

assetPropertiesCardConfig:
  name:
    displayName: Asset name
    orderNumber: 1
  description:
    displayName: Description
    orderNumber: 2
  parentAsset:
    displayName: Parent asset
  tags:
    orderNumber: 3
dataExplorationConfig:
  assetActivitiesCardView:
    space: customer_idm_extension
    externalId: InfieldActivitiesCardView
    version: v4
    type: view
  assetNotificationsCardView:
    space: customer_idm_extension
    externalId: InfieldNotificationsCardView
    version: v2
    type: view

All keys are optional. Deploy configuration changes through the Cognite Toolkit to ensure view references are validated before deployment.

Properties card (`assetPropertiesCardConfig`)

Configured via the top-level assetPropertiesCardConfig field. Falls back to showing all fields from the view in viewMappings.asset. Each key in the map is a field name from the asset view. Each entry supports:

Property	Required	Description
`displayName`	No	Label shown in the UI. If omitted, InField uses the property name from the view.
`orderNumber`	No	Display order. Properties without an `orderNumber` appear after ordered ones in unspecified order.

Activities card (`assetActivitiesCardView`)

Configured via dataExplorationConfig.assetActivitiesCardView. Falls back to viewMappings.maintenanceOrder when omitted. The view name becomes the card header, and the view filter controls which activities are shown. The view must expose the following properties:

Property in view	Purpose
`sourceId`	Identifier from the source system
`name`	Primary display value for the activity row
`status`	Status shown in the row
`type`	Type shown in the row
`mainAsset`	Related asset reference
`scheduledStartTime`	Planned start time
`scheduledEndTime`	Planned end time

Notifications card (`assetNotificationsCardView`)

Configured via dataExplorationConfig.assetNotificationsCardView. Falls back to viewMappings.notification when omitted. The view name becomes the card header and the view filter controls which notifications are shown. The view must expose the following properties:

Property in view	Purpose
`name`	Primary display value for the notification row
`sourceId`	Identifier from the source system
`type`	Notification type
`status`	Current status
`priority`	Priority shown in the row
`createdDate`	Creation date shown in the row
`asset`	Related asset reference
`description`	Additional descriptive text

Administration

Configure InField on CDM

Before you start

Enable Core Data Model (CDM) mode

How CDM configuration works

Set up access

Create data modeling spaces

Prepare asset data

Configure locations

View mappings (`viewMappings`)

Data storage (`dataStorage`)

Instance space scoping (`dataFilters`)

Feature toggles (`featureToggles`)

Admin roles (`accessManagement`)

Disciplines (`disciplines`)

Configure schedules

Configure observations

SAP writeback

Configure asset explorer cards (`dataExplorationConfig`)

Properties card (`assetPropertiesCardConfig`)

Activities card (`assetActivitiesCardView`)

Notifications card (`assetNotificationsCardView`)

Further reading

​Before you start

​Enable Core Data Model (CDM) mode

​How CDM configuration works

​Set up access

​Create data modeling spaces

​Prepare asset data

​Configure locations

​View mappings (viewMappings)

​Data storage (dataStorage)

​Instance space scoping (dataFilters)

​Feature toggles (featureToggles)

​Admin roles (accessManagement)

​Disciplines (disciplines)

​Configure schedules

​Configure observations

​SAP writeback

​Configure asset explorer cards (dataExplorationConfig)

​Properties card (assetPropertiesCardConfig)

​Activities card (assetActivitiesCardView)

​Notifications card (assetNotificationsCardView)

​Further reading

Before you start

Enable Core Data Model (CDM) mode

How CDM configuration works

Set up access

Create data modeling spaces

Prepare asset data

Configure locations

View mappings (`viewMappings`)

Data storage (`dataStorage`)

Instance space scoping (`dataFilters`)

Feature toggles (`featureToggles`)

Admin roles (`accessManagement`)

Disciplines (`disciplines`)

Configure schedules

Configure observations

SAP writeback

Configure asset explorer cards (`dataExplorationConfig`)

Properties card (`assetPropertiesCardConfig`)

Activities card (`assetActivitiesCardView`)

Notifications card (`assetNotificationsCardView`)

Further reading