Import activities from CSV file
You can use the activity import functionality to import multiple activities into Maintain from an external source. This allows you to upload a text file in the CSV (Comma-separated values) format containing activity data and ingest them into activities in Maintain. These activities can then be visualized and modified as if they were created directly in Maintain.
Downloading the CSV file template
The CSV file that is imported needs to conform to your project-specific template.
To download the template:
- Navigate to Activities and select Add activity.
- Select Import activities.
- Select Download template.
The maintain-import-template.csv is now downloaded.
Populating 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 should not 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 is not 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
Creating a CSV file with an additional row:
title,status,department
Erect scaffolding,Done,Rigging
Will result in an activity being created with the title "Erect scaffolding", status "Done," and department "Rigging" when imported.
Formatting 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 file:
title,startTime (DD/MM/YYYY)
Erect scaffolding,10/12/2023
Will result in the activity being created with startTime set to December 10th 2023.
Formatting boolean fields
Some activity fields in Maintain represent boolean values, i.e., true/false. Date 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 file:
title,isActive (true/false)
Erect scaffolding,false
Will result in the activity being created with isActive set to false.
Formatting 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 file:
title,city
Erect scaffolding,"Boston, MA"
Will result in the activity being created with city set to Boston, MA.
Unset values
On non-required activity fields, you can leave the field blank to represent missing or irrelevant values for the specific activity.
For example, importing the file:
title,city,state
Erect scaffolding,,New York
Will result in the activity being created with state set to New York, but it will have no value on the city field.
Contextualizing 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 asset contextualization is enabled on your project, there will be a special assetExternalId field in the template that needs to be populated with an appropriate external ID of the activity's asset.
For example, when importing the file:
title,assetExternalId
Erect scaffolding,NY_BUILDING_23
Assuming a CDF asset exists with external id NY_BUILDING_23, the activity will be contextualized to this asset when ingested into Maintain.
If the provided external ID does not export, the user will be shown an error during import.
End-users may not know the external ID of the asset to which the activity is linked. If it is 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.
Importing a populated CSV file into Maintain
Once you have a populated CSV template, you can import it into Maintain like this:
- Navigate to the Activities and select Add activity.
- Select Import activities.
- Select the blue box Click to select CSV file to import.
- Use the file browser to find and upload the populated CSV file.
- Verify that the file was successfully imported by checking the File Inspector section below the blue box. A green message should tell you the number of rows about to be imported and any warnings or errors.
- If there are no errors, select Import to start the import process.
- If the import succeeds, a green success message containing a Show activities button will be shown. Optionally, click this button to navigate to the imported activities and check that they look correct according to the CSV file.