> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# InField Quickstart reference

> Configure Cognite InField per location on the Core Data Model (CDM) and the Industry Data Model (IDM) — instance spaces, location configuration, role-based access groups, and a Fusion location filter for a single plant or site.

The **InField Quickstart deployment pack** (`dp:infield`) is a per-location pack for configuring [InField](/cdf/infield/index) on a Cognite Data Fusion project. It creates the instance spaces, InField location configuration, access groups, and a Fusion location filter needed to run InField at a single plant or site. The pack uses CDM and IDM standard views directly — no custom data model is required — and is designed to be copied once per location to support multi-site deployments.

InField is Cognite's field execution application: field workers use it to [complete tasks](/cdf/infield/guides/perform) and [capture measurements and observations](/cdf/infield/guides/observations) with full traceability. Supervisors and planners use it to [plan and assign work](/cdf/infield/guides/plan), [build templates and checklists](/cdf/infield/guides/create_templates), and monitor operational progress. This pack handles the CDF-side configuration so the application is ready to connect to your project's IDM-based data from day one. For an overview of the application, see [About Cognite InField](/cdf/infield/index).

## Who it's for

**Target personas:**

* **Data engineers** — configure and deploy InField for one or more plant or site locations.
* **Subject matter experts** — maintenance and operations leads who define the InField setup.

**Use this pack when:**

* You are setting up a new InField location on a CDF project that already has IDM-based asset, maintenance, and notification data.
* You need repeatable, environment-consistent InField configuration across `dev`, `test`, and `prod`.
* You are adding a second or third location to an existing InField deployment — copy the module folder once per site.
* You want role-based access control (read-only, normal, template admin, checklist admin) wired to IdP groups from the start.

**When not to use this pack:**

* If your project uses the legacy APM-based maintenance order model. InField requires `cdf_idm/CogniteMaintenanceOrder/v1` — migrate to IDM before deploying.
* If your CDF project does not yet have IDM-compatible source data (assets, maintenance orders, operations, notifications) loaded. Deploy and populate your data model first.

## What's included

The pack ships a single module, `cdf_infield_location`, that you copy once per location.

| Component                      | Description                                                                                                                                                                                                                                                                                                                               | Optional? |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `cdf_infield_location`         | Core module — creates all spaces, the InField location configuration, and the four access groups for a single location. Copy this folder once per additional site.                                                                                                                                                                        | No        |
| Instance spaces (6)            | `sp_infield_{{location}}_app_inst`, `sp_infield_{{location}}_cfg_inst`, `sp_infield_{{location}}_assets`, `sp_infield_{{location}}_maintenance`, `sp_infield_{{location}}_timeseries`, and `sp_infield_{{location}}_files`.                                                                                                               | No        |
| InField location configuration | `InFieldCDMLocationConfig` instance — ships default view mappings, feature toggles (3D, trends, documents, work orders, notifications, media, templates and checklists, observations, and Copilot), the discipline list, and instance space routing for each data type. You review and complete these in the InField UI after deployment. | No        |
| Access groups (4 roles)        | `infield_location_read_only_role`, `infield_location_normal_role`, `infield_location_template_admin_role`, and `infield_location_checklist_admin_role` — each bound to an IdP source ID via an environment variable.                                                                                                                      | No        |
| Fusion location filter         | `LocationFilter` YAML scoping the same location data in Fusion, so asset and maintenance data is accessible consistently across both applications.                                                                                                                                                                                        | Yes       |

## Prerequisites

Verify all of the following before you start:

* Cognite Toolkit version **0.8 or later** is installed. See [Setting up](/cdf/deploy/cdf_toolkit/guides/setup).
* A `cdf.toml` file exists in your project root. If it is missing, run `cdf modules init` and select **Create toml file (required)**.
* Authentication is configured and verified — run `cdf auth init` and `cdf auth verify` using a local `.env` file. See [Authentication and authorization](/cdf/deploy/cdf_toolkit/guides/auth).
* IDM-based source data is already loaded into CDF — an asset hierarchy, maintenance orders, operations, notifications, time series, and files in IDM-compatible spaces. InField requires `cdf_idm/CogniteMaintenanceOrder/v1`.
* Four IdP group source IDs from your identity team — one each for read-only users, normal users, template admins, and checklist admins. Set these as environment variables before running `cdf deploy`.

## Install and deploy

You can add the InField location module to an existing Toolkit project or start a new project from scratch.

<Tabs>
  <Tab title="Add to an existing project">
    Add the InField module from your project directory:

    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf modules add -d cdf_infield_location
    ```
  </Tab>

  <Tab title="Start a new project">
    1. In an empty directory, initialize a project:

       ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
       cdf modules init .
       ```

    2. In the interactive menu, choose **Solutions**, use **Space** to select **Infield Location**, then press **Enter** to confirm.
  </Tab>
</Tabs>

The Toolkit creates the module under `modules/solutions/cdf_infield/cdf_infield_location/` and updates your `config.<env>.yaml` files. Before building, add the four IdP group source IDs to your project `.env` file (next to `cdf.toml`):

```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
INFIELD_LOCATION_READ_ONLY_USERS_SOURCE_ID=<source-id>
INFIELD_LOCATION_NORMAL_USERS_SOURCE_ID=<source-id>
INFIELD_LOCATION_TEMPLATE_ADMIN_USERS_SOURCE_ID=<source-id>
INFIELD_LOCATION_CHECKLIST_ADMIN_USERS_SOURCE_ID=<source-id>
```

Open `config.dev.yaml` and set at minimum `location`, `location_name`, and the location description — see [Configuration reference](#configuration-reference). Then build and deploy:

<Steps>
  <Step title="Build deployment artifacts">
    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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](/cdf/deploy/cdf_toolkit/guides/usage).
  </Step>

  <Step title="Dry-run the deployment">
    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf deploy --dry-run
    ```

    Inspect the output and confirm that configurations look correct before deploying.
  </Step>

  <Step title="Deploy to CDF">
    ```sh theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf deploy
    ```

    The Toolkit deploys only configurations that have changed since the last run.
  </Step>

  <Step title="Set up CI/CD (optional)">
    For governed production deployments, automate build, dry-run, and deploy in a pipeline. See [Set up CI/CD pipelines](/cdf/deploy/cdf_toolkit/guides/cicd/index).
  </Step>
</Steps>

## Configure InField in the user interface

The Toolkit deploys the location configuration with default view mappings, but you confirm and complete the following in the InField application — view mappings and the asset explorer are set in the UI. Open [InField](https://cognite-infield.cogniteapp.com) and go to **Settings (⚙)**. For full details on these settings, see [Configure data models for InField](/cdf/infield/guides/config_idm).

<Steps>
  <Step title="Add the location">
    Go to **Settings** > **Add location** and enter the location name, description, and location code.
  </Step>

  <Step title="Configure view mappings">
    Under the location settings, set the view mappings:

    * **Asset views** — your CDM or IDM asset view (default: `cdf_cdm / CogniteAsset / v1`).
    * **Activities and operations** — default: `cdf_idm / CogniteOperation / v1`.
    * **Notifications** — default: `cdf_idm / CogniteNotification / v1`.
    * **Maintenance orders** — must be `cdf_idm / CogniteMaintenanceOrder / v1`; APM-based models are not supported.
  </Step>

  <Step title="Select instance spaces">
    Set the **Customer instance space** to your source data space (for example, `sp_infield_{{location}}_assets`) and the **InField instance space** to the app data space (`sp_infield_{{location}}_app_inst`).
  </Step>

  <Step title="Configure the asset explorer">
    Set the asset hierarchy root, display fields, and associated time series under the asset explorer settings for the location.
  </Step>
</Steps>

## Verify the deployment

After deploying and completing the manual location setup, confirm success with these checks:

1. The `cdf deploy` command finishes without errors and reports successful deployment of spaces and groups.
2. In CDF, navigate to **Data Modeling > Spaces** and verify that all six location spaces exist: `sp_infield_{{location}}_app_inst`, `sp_infield_{{location}}_cfg_inst`, `sp_infield_{{location}}_assets`, `sp_infield_{{location}}_maintenance`, `sp_infield_{{location}}_timeseries`, and `sp_infield_{{location}}_files`.
3. Navigate to **Access management > Groups** and verify that all four InField groups exist and are bound to the correct IdP source IDs.
4. Open the InField application and confirm that the configured location appears in the location list.
5. Use the InField search to look up assets, work orders, and notifications. Results should return data from the correct instance spaces.
6. Verify role-based access by signing in with a user from each group and confirming the expected permissions apply — read-only users cannot edit, and template admins can manage templates.

The deployment is successful when all six spaces exist, all four groups are active, the InField location is visible and navigable, and search returns data.

## Configuration reference

Parameters are set in `config.dev.yaml` at the project root, and IdP source IDs are set in the project `.env` file. Default values work for an initial single-location test deployment.

Each parameter takes its default unless you override it. The defaults are demo placeholders (`springfield`) — replace them with your own location before deploying to a real site.

| Parameter              | Description                                                                                                                        | Default                 |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `location`             | Location slug — used in all space names and the location config external ID. Use lowercase letters, numbers, and underscores only. | `springfield`           |
| `location_name`        | Human-readable location name shown in the InField user interface.                                                                  | `Springfield`           |
| `location_description` | Short description of the location shown in InField.                                                                                | `Springfield site demo` |
| `module_version`       | Version tag for the location configuration instance.                                                                               | `v1`                    |

### IdP source IDs

Set these in the project `.env` file — all four are required. They are injected at deploy time via the Toolkit's `${VAR}` substitution, so credentials stay out of source control. These are object IDs, not secrets.

| Variable                                           | Description                                                    |
| -------------------------------------------------- | -------------------------------------------------------------- |
| `INFIELD_LOCATION_READ_ONLY_USERS_SOURCE_ID`       | IdP source ID for the read-only InField users group.           |
| `INFIELD_LOCATION_NORMAL_USERS_SOURCE_ID`          | IdP source ID for the standard (field technician) users group. |
| `INFIELD_LOCATION_TEMPLATE_ADMIN_USERS_SOURCE_ID`  | IdP source ID for the template admin group.                    |
| `INFIELD_LOCATION_CHECKLIST_ADMIN_USERS_SOURCE_ID` | IdP source ID for the checklist admin group.                   |

<Note>
  To deploy a second location, copy the `cdf_infield_location` folder, give it a unique name (for example, `cdf_infield_location_oslo`), update the `id` in its `module.toml`, register it in `modules/packages.toml`, and provide a separate set of IdP source IDs. Each copy deploys fully independently.
</Note>

## Architecture

The pack deploys a single module (`cdf_infield_location`) that creates all CDF-side resources for one InField location. There is no custom data model — InField reads directly from CDM and IDM standard views. The module is intentionally scoped to one location so that multiple sites remain independent: a failure or reconfiguration in one location does not affect others.

### Instance spaces

| Space                                 | Purpose                                                                                                                                                 |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sp_infield_{{location}}_app_inst`    | InField app data — templates, checklists, observations, and uploaded images written by InField at runtime.                                              |
| `sp_infield_{{location}}_cfg_inst`    | InField location configuration instance (`InFieldCDMLocationConfig`) — view mappings, feature toggles, and data filter routing.                         |
| `sp_infield_{{location}}_assets`      | Source asset hierarchy from CMMS or SAP, loaded by the project's ingestion pipeline.                                                                    |
| `sp_infield_{{location}}_maintenance` | Maintenance orders (`CogniteMaintenanceOrder`), operations (`CogniteOperation`), and notifications (`CogniteNotification`) — must all share this space. |
| `sp_infield_{{location}}_timeseries`  | Time series data accessible in InField trends and the asset explorer.                                                                                   |
| `sp_infield_{{location}}_files`       | Documents and file attachments associated with assets and work orders.                                                                                  |

### Default view mappings

| InField entity    | Default CDM or IDM view                  |
| ----------------- | ---------------------------------------- |
| Asset             | `cdf_cdm / CogniteAsset / v1`            |
| Maintenance order | `cdf_idm / CogniteMaintenanceOrder / v1` |
| Operation         | `cdf_idm / CogniteOperation / v1`        |
| Notification      | `cdf_idm / CogniteNotification / v1`     |
| File              | `cdf_cdm / CogniteFile / v1`             |

If your project uses extended views (for example, a custom `ExtendedMaintenanceOrder` view in a project space), update the `viewMappings` section of `infield_location.InFieldCDMLocationConfig.yaml` before deploying.

### Access groups

| Group                                   | Purpose                                                                                                       |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `infield_location_read_only_role`       | View-only access to InField — can navigate assets, work orders, and notifications but cannot edit or execute. |
| `infield_location_normal_role`          | Standard field technician access — can execute checklists, capture observations, and update task status.      |
| `infield_location_template_admin_role`  | Can create and manage InField templates in addition to normal access.                                         |
| `infield_location_checklist_admin_role` | Can create, assign, and manage checklists in addition to normal access.                                       |

### Key design decisions

**One module per location.** Each location is a fully independent copy of `cdf_infield_location` with its own spaces and groups. This avoids shared-state conflicts between sites and lets each location be deployed, updated, or rolled back independently.

**No custom data model.** InField reads directly from CDM (`cdf_cdm`) and IDM (`cdf_idm`) standard views. The pack configures which views InField uses and where data lives — it does not define a schema. Project-specific extended views can be substituted via `viewMappings` without changing the module structure.

**Maintenance, operations, and notifications share one space.** The `sp_infield_{{location}}_maintenance` space holds all three entity types. This is a hard requirement from InField: the data filters for maintenance orders, operations, and notifications must point to the same instance space.

**IdP source IDs via environment variables.** Group source IDs are never stored in YAML — they are injected at deploy time via the Toolkit's `${VAR}` substitution from the project `.env` file. This keeps IdP credentials out of source control and makes the same module YAML reusable across environments.

## Troubleshooting

| Symptom                                            | Likely cause                                                                                              | Resolution                                                                                                                                                                                                                               |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cdf auth verify` fails with 401 Unauthorized      | Missing or incorrect credentials in `.env` file.                                                          | Run `cdf auth init`, re-enter credentials, then re-run `cdf auth verify`.                                                                                                                                                                |
| Module not found during `cdf modules add`          | `[library.cognite]` not configured in `cdf.toml`, or `[library.toolkit-data]` still present alongside it. | Replace `[library.toolkit-data]` with `[library.cognite]` in `cdf.toml`. The two sections cannot coexist.                                                                                                                                |
| `cdf deploy` fails with "Insufficient permissions" | Toolkit service account is missing required CDF capabilities.                                             | Add `spaces:write`, `groups:write`, and `datasets:write` to the CDF group used by the Toolkit.                                                                                                                                           |
| Groups deploy with empty source IDs                | IdP environment variables not set before running `cdf deploy`.                                            | Ensure all four `INFIELD_LOCATION_*_SOURCE_ID` variables are present in your `.env` file and re-run `cdf deploy`.                                                                                                                        |
| InField shows no data after the location is added  | Instance spaces are empty — source data not yet loaded to the configured spaces.                          | Verify that assets, maintenance orders, operations, and notifications have been ingested to the correct `sp_infield_{{location}}_*` spaces. Check that the data filters in `InFieldCDMLocationConfig` match the spaces where data lives. |
| Maintenance orders not visible in InField          | Source data uses the APM-based maintenance order model instead of IDM.                                    | InField requires `cdf_idm / CogniteMaintenanceOrder / v1`. Migrate source data to the IDM view before deploying.                                                                                                                         |
| Users cannot sign in to InField                    | Wrong IdP source ID mapped to an InField group, or users not added to the IdP group.                      | Verify the source IDs in **Access management** match the IdP group object IDs. Confirm users are members of the correct IdP group.                                                                                                       |
| Second location conflicts with the first           | The copied module folder was not given a unique `id` in `module.toml`.                                    | Edit `module.toml` in the copied folder and set a unique `id` (for example, `dp:infield:cdf_infield_location_oslo`). Also register the path in `modules/packages.toml`.                                                                  |

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](https://hub.cognite.com/groups/578) |
| Version                | 1.0.0                                                                       |
| Last updated           | 2026                                                                        |