> ## 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.

# Import activities into Maintain

> Learn how to import activities using the user interface (APM mode), Cognite Toolkit, or Transformations.

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](/cdf/deploy/cdf_toolkit/) data modeling (APM and IDM/CDM modes).
* **Transformations**: Convert data from RAW tables or other sources using [CDF Transformations](/cdf/integration/) (APM and IDM/CDM modes).

## Import via CSV upload (APM mode)

<Info>
  **Mode availability**: APM mode only. IDM/CDM mode doesn't support CSV import in the user interface.
</Info>

Activities imported via CSV can be visualized and modified as activities created in Maintain.

<Steps>
  <Step title="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**.
  </Step>

  <Step title="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.

    <Tip>
      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.
    </Tip>

    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.

    <a id="format-date-fields" />

    ### 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
    ```

    <a id="format-boolean-fields" />

    ### 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
    ```

    <a id="format-values-containing-commas" />

    ### 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](https://www.rfc-editor.org/rfc/rfc4180), 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"
    ```

    <a id="unset-values" />

    ### 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
    ```

    <a id="connect-an-activity-to-an-asset" />

    ### 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.

    <Tip>
      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](/api-reference/concepts/20230101/assets) or other data extractors.
    </Tip>
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Import via Cognite Toolkit

<Info>
  **Mode availability**: APM and IDM/CDM modes. This is the recommended approach for programmatic activity ingestion.
</Info>

Use the [Cognite Toolkit](/cdf/deploy/cdf_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](/cdf/deploy/cdf_toolkit/)

### Configure the activity view mapping

In your Maintain configuration, verify that the `viewMappings` section points to your activity view:

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
"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:

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
"viewMappings": {
  "activity": {
    "type": "view",
    "space": "maintain_schema_extention",
    "version": "v1",
    "externalId": "APM_Activity"
  }
}
```

Learn more about [extending data models](/cdf/maintain/guides/config#extend-data-models) and [configuring view mappings](/cdf/maintain/guides/config#view-mappings).

### Ingest activities with the Cognite Toolkit

Use the [Cognite Toolkit](/cdf/deploy/cdf_toolkit/) as the recommended approach for ingesting activities in IDM mode.

<Steps>
  <Step title="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](/cdf/deploy/cdf_toolkit/) for detailed examples and templates.
  </Step>

  <Step title="Configure field mappings">
    Ensure your activity nodes include the required fields for Maintain:

    | Field             | Description                                                  | Required    |
    | ----------------- | ------------------------------------------------------------ | ----------- |
    | `externalId`      | Unique identifier for the activity                           | Yes         |
    | `title`           | Activity title                                               | Yes         |
    | `status`          | Activity status (for example, "Open", "In Progress", "Done") | Recommended |
    | `startTime`       | Start date/time                                              | Recommended |
    | `endTime`         | End date/time                                                | Recommended |
    | `rootLocation`    | Root location identifier                                     | Recommended |
    | `assetExternalId` | External ID of linked asset                                  | Optional    |
    | `mainAsset`       | Direct relation to asset                                     | Optional    |

    <Tip>
      Include additional fields based on your [Field Configuration](/cdf/maintain/guides/config#field-configuration) settings in Maintain.
    </Tip>
  </Step>

  <Step title="Deploy the activities">
    Deploy your activity data using Cognite Toolkit:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf deploy --env dev
    ```

    Use the `--drop-data` flag if you need to replace existing activities:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    cdf deploy --env dev --drop-data
    ```

    Learn more about the [Cognite Toolkit deployment flags](/cdf/maintain/guides/config#critical-deployment-flags).
  </Step>

  <Step title="Verify in Maintain">
    1. Sign in to [Maintain](https://maintain.cogniteapp.com).
    2. Navigate to **Activities**.
    3. Verify that your imported activities appear with the correct data.
  </Step>
</Steps>

### Ingest activities with Transformations

<Info>
  **Mode availability**: APM and IDM/CDM modes. This is the recommended approach for bulk data.
</Info>

Alternatively, you can use [CDF Transformations](/cdf/integration/) 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.

| Issue                  | Solution                                                                               |
| ---------------------- | -------------------------------------------------------------------------------------- |
| Activities not visible | Verify the `viewMappings` configuration points to the correct space, view, and version |
| Missing fields         | Check that your Field Configuration includes all the fields you're ingesting           |
| Asset links broken     | Ensure `assetExternalId` or `mainAsset` relations point to existing assets             |
| Wrong root location    | Verify `rootLocation` matches your location configuration                              |