Skip to main content

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.

Maintain supports three methods for importing activities:
  • CSV upload: Import activities using the user interface (APM mode only).
  • Cognite Toolkit: Ingest activities using Cognite Toolkit data modeling (APM and IDM/CDM modes).
  • Transformations: Convert data from RAW tables or other sources using CDF Transformations (APM and IDM/CDM modes).

​
Import via CSV upload (APM mode)

Mode availability: APM mode only. IDM/CDM mode doesn’t support CSV import in the user interface.
Activities imported via CSV can be visualized and modified as activities created in Maintain.
1

Download the CSV file template

The imported CSV file needs to conform to your project-specific template. To download maintain-import-template.csv:
  1. Navigate to Activities and select Add activity.
  2. Select Import activities.
  3. Select Download template.
2

Populate the CSV file template

The CSV template will only contain a single row of values representing the possible values you can provide for an imported activity. This row is called the header row and shouldn’t be removed when populating the template.
While the header row must not be removed, you can remove specific values from the header or change the order of the values. For example, if a certain field isn’t relevant to import in a specific scenario, you can remove it from the header and the subsequent rows. This will result in the field being left blank on all imported activities.
To import a single activity, add a new row to the template and enter the appropriate values separated by commas. Each value in the new row should contain the value you want to populate on the respective header row that was provided in the template.For example, if your template contains the following header row: title,status,department, create a CSV file with an additional row:
title,status,department
Erect scaffolding,Done,Rigging
You’ll create an activity with the title “Erect scaffolding”, status “Done,” and department “Rigging” when imported.

​
Format date fields

Some activity fields in Maintain represent dates and must have a specific format to be properly imported. Date fields can be identified in the CSV template by a special header value in the form startTime (DD/MM/YYYY). In this example, startTime is the name of the field, while DD/MM/YYYY is the date format that needs to be used in subsequent rows of the CSV file.For example, importing the following file will result in the activity being created with startTime set to December 10th 2023.
title,startTime (DD/MM/YYYY)
Erect scaffolding,10/12/2023

​
Format boolean fields

Some activity fields in Maintain represent boolean values, such as true or false. Boolean fields can be identified in the CSV template by a special header value in the form isActive (true/false). These fields only have two valid values, true or false.For example, importing the following file will result in the activity being created with isActive set to false.
title,isActive (true/false)
Erect scaffolding,false

​
Format values containing commas

Due to the CSV format separating values using commas, be careful when an activity field also needs to contain a comma. Maintain processes CSV files according to the RFC 4180 standard, which requires values containing commas to be wrapped in double quotes.For example, importing the following file will result in the activity being created with city set to Boston, MA.
title,city
Erect scaffolding,"Boston, MA"

​
Unset values

You can leave the field blank on non-required activity fields to represent missing or irrelevant values for the specific activity.For example, importing the following file will result in the activity being created with state set to New York, but it will have no value in the city field.
title,city,state
Erect scaffolding,New York

​
Connect an activity to an asset

Maintain supports linking activities to CDF assets, which is used to contextualize the activity in 3D models, documents, PSN, and more. For Maintain to create the appropriate link to an asset in CDF, you must provide the CDF asset’s external ID in the import template.If you have asset contextualization in your project, there will be a special assetExternalId field in the template that you need to populate with the external ID of the activity’s asset.For example, when importing the following file and assuming a CDF asset exists with external ID NY_BUILDING_23, the activity will be contextualized to this asset when ingested into Maintain.
title,assetExternalId
Erect scaffolding,NY_BUILDING_23
If the provided external ID doesn’t export, the user will see an error during import.
End-users may not know the external ID of the asset to which the activity is linked. If it’s necessary to provide end-users with a list of the possible assets and their external IDs, we recommend retrieving this data using CDF’s asset API or other data extractors.
3

Import a populated CSV file

Once you have a populated CSV template, you can import it into Maintain:
  1. Navigate to Activities > Add activity.
  2. Select Import activities.
  3. Select the Click to select CSV file to import field.
  4. Select and upload the populated CSV file from your computer.
  5. Verify that you imported the file by checking the File Inspector section. A green message should show the number of rows to be imported and if you have any warnings or errors.
  6. If there are no errors, select Import to start the import process.
  7. When the import succeeds, you’ll see a green success message with the Show activities button.
  8. Optional. Select Show activities to navigate to the imported activities and check that they look correct according to the CSV file.

​
Import via Cognite Toolkit

Mode availability: APM and IDM/CDM modes. This is the recommended approach for programmatic activity ingestion.
Use the Cognite Toolkit to ingest activities through CDF’s data modeling capabilities. This method works for both deployment modes and provides version control and reproducible deployments.

​
Prerequisites

Before importing activities via the Cognite Toolkit, ensure you have:
  • A custom activity view configured in your data model space (or use the standard CogniteMaintenanceOrder view from cdf_idm)
  • The activity view mapped in your Maintain configuration under viewMappings
  • Access to the Cognite Toolkit

​
Configure the activity view mapping

In your Maintain configuration, verify that the viewMappings section points to your activity view: 
"viewMappings": {
  "activity": {
    "type": "view",
    "space": "cdf_idm",
    "version": "v1",
    "externalId": "CogniteMaintenanceOrder"
  }
}
If you’ve created a custom activity view (for example, APM_Activity or ExtendedActivity), update the mapping to point to your custom view: 
"viewMappings": {
  "activity": {
    "type": "view",
    "space": "maintain_schema_extention",
    "version": "v1",
    "externalId": "APM_Activity"
  }
}
Learn more about extending data models and configuring view mappings.

​
Ingest activities with the Cognite Toolkit

Use the Cognite Toolkit as the recommended approach for ingesting activities in IDM mode.
1

Create the activity data structure

If you haven’t already, create Container, View, and Node YAML files for your activities. Follow the standard data modeling structure:
  • APM_Activity.Container.yaml - Defines the container schema
  • APM_Activity.View.yaml - Defines the view properties and relationships
  • apmActivities.Node.yaml - Contains your activity instances
See the Cognite Toolkit documentation for detailed examples and templates.
2

Configure field mappings

Ensure your activity nodes include the required fields for Maintain:
FieldDescriptionRequired
externalIdUnique identifier for the activityYes
titleActivity titleYes
statusActivity status (for example, “Open”, “In Progress”, “Done”)Recommended
startTimeStart date/timeRecommended
endTimeEnd date/timeRecommended
rootLocationRoot location identifierRecommended
assetExternalIdExternal ID of linked assetOptional
mainAssetDirect relation to assetOptional
Include additional fields based on your Field Configuration settings in Maintain.
3

Deploy the activities

Deploy your activity data using Cognite Toolkit:
cdf deploy --env dev
Use the --drop-data flag if you need to replace existing activities:
cdf deploy --env dev --drop-data
Learn more about the Cognite Toolkit deployment flags.
4

Verify in Maintain

  1. Sign in to Maintain.
  2. Navigate to Activities.
  3. Verify that your imported activities appear with the correct data.

​
Ingest activities with Transformations

Mode availability: APM and IDM/CDM modes. This is the recommended approach for bulk data.
Alternatively, you can use CDF Transformations to convert data from RAW tables or other sources into activity nodes.

​
Troubleshooting

If you encounter issues with activities after ingestion, see the table for causes and fixes.
IssueSolution
Activities not visibleVerify the viewMappings configuration points to the correct space, view, and version
Missing fieldsCheck that your Field Configuration includes all the fields you’re ingesting
Asset links brokenEnsure assetExternalId or mainAsset relations point to existing assets
Wrong root locationVerify rootLocation matches your location configuration
Last modified on April 28, 2026