Configure Maintain

Before you start

Make sure you have the following:

1. A project registered in the CDF application.
2. 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.
3. Assets in the CDF project populated in the CogniteAsset concept .
4. URLs in your allowlist.

Create data modeling spaces

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

Space name	Description
cdf_apps_shared	This space holds user data, such as user profiles, and application configuration.
yourRootLocation_source_data	This space holds space data (data coming from a customer source system, such as SAP) for a particular location.
yourRootLocation_app_data	This space holds data coming from Maintain (from plans and layouts) for a particular location.

tip

Create new yourRootLocation_source_data and yourRootLocation_app_data spaces for each root location you have if you want to implement access control per location.

You can create spaces in the following ways:

• With the Cognite Python SDK.
• With the Cognite API.

Spaces created with SDK

You can create the spaces using Cognite Python SDK. Use the following Python code and replace yourRootLocation with your root location/asset name in yourRootLocation_source_data, 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", "cdf_apps_shared"]

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

Spaces created with API

Create the spaces using the API endpoint:

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, yourRootLocation_app_data.

Set up access

You can use your existing identity provider (IdP) framework to manage access to Maintain and choose admin users. We currently support Microsoft Entra ID, Microsoft's cloud-based identity and access management service. By creating groups, you can assign different sets of capabilities to users and give each group different access rights.

Create admin group

tip

If you have an admin group with the same capabilities, you can reuse that group and skip this step.

Create a group of users who can configure the Maintain application across all locations. See also how to configure locations.

1. Go to CDF > Manage > Manage access.
2. Give read and write access to all capabilities with the scope All, or have the minimum set of capabilities.

Capability type	Action	Scope	Description
Groups	groups: read, groups: list	All	For Maintain administrators to grant access to users.
Data models	dataModel: read	All	View data models.
Data model instances	dataModelInstance:read	All	Access data organized in data models.
Data model instances	dataModelInstance:write	cdf_apps_shared	Access and edit data organized in data models and spaces.

Create user groups

Create groups of users who can view activities, create plans and campaigns, and work with different layouts. You can create several groups with different capabilities. The suggested group is an example you can use.

Name	Description
maintain_plans	Users in the group can view and edit plans and layouts.

note

Group names are suggestions and can differ from user to user.

Assign the following group capabilities:

Capability type	Action	Scope	Description
Groups	groups: read, groups: list	All	View user groups.
Data models	dataModel: read	cdf_cdm, cdf_idm, cdf_maintain, cdf_apps_shared , idm_customer_datamodel_space- the space where you extend the views	View and analyze the data created in Maintain.
Data model instances	dataModelInstance:read	cdf_apps_shared, location_app_data_space, location_source_data_space - a list of spaces to read the data from. Add all spaces you want to read the data from to the scope.	View and analyze the data created in Maintain.
Data model instances	dataModelInstance:write	cdf_apps_shared	Access and edit data organized in data models and spaces.

Ingest data into data models

All data for Maintain is stored within data models, with a few exceptions.

Generally, most tabular data is expected to exist inside RAW. Once the data is in RAW, use transformations to change this data into one of the following data models, depending on the view. Most of the data entries are required to use the application effectively. It's recommended to ingest the data entities in the order they appear in the table. Once you ingest Assets and Maintenance Orders, open the application to check that this data appears correctly.

Data entity	View
Asset	cdf_cdm.Asset
Maintenance Orders (Work Orders)	cdf_idm.CogniteMaintenanceOrder
Operations	cdf_idm.Operations
Files (P&IDs)	cdf_cdm.File
Annotations (File Contextualisation)	cdf_cdm.DiagramAnnotation (edge)
3D	Ingested through 3D APIs

tip

It's recommended to use the existing 3D APIs to ingest 3D data even though the data ends up in data modeling.

You can also use the Cognite Toolkit to ingest data into data models.

You don't need to ingest any data in the Plan and Comment data entries, as Maintain will use pre-existing data models to ingest data.

Data entity	View
Plan	cdf_maintain.Plan
Comment	cdf_apps_shared.Comment

Configure Maintain

Once you have data ingested, the final step is to create a location configuration for Maintain to use.

1. Sign in to Maintain with your organization ID.
2. Select the spaces for the source data (yourRootLocation_source_data) and for the application data (yourRootLocation_app_data).

A basic configuration is set up. The configuration uses JSON and allows flexibility in how you view Maintain. You can see examples of Field Configuration and Feature Configuration.

Extend data models

Views contain a group of properties that you can change for specific cases. By default, Maintain uses Cognite process industries data model that extends the core data model to meet the requirements for the process industries. You can customize entity definitions or views, such as CogniteAsset and CogniteMaintenanceOrder, by adding 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 to this property.

In Maintain, you can filter on the entities, such as activities, assets, etc., with views defined in the cdf_idm (Process industries data model), cdf_cdm (Core data model) spaces, or the space with customized views.

To set up how you want to query CDF data modeling:

1. Sign in to Maintain with your organization ID.
2. Under Cognite Maintain, select the dropdown > yourConfig > edit (✏️).
3. In Feature Configuration, you'll see your view mappings.

"viewMappings": {
    "asset": {
      "type": "view",
      "space": "cdf_cdm",
      "version": "v1",
      "externalId": "CogniteAsset"
    },
    "activity": {
      "type": "view",
      "space": "cdf_idm",
      "version": "v1",
      "externalId": "CogniteMaintenanceOrder"
    },
     "operation": {
      "type": "view",
      "space": "cdf_idm",
      "version": "v1",
      "externalId": "CogniteOperation"
    },
    "notification": {
      "type": "view",
      "space": "cdf_idm",
      "version": "v1",
      "externalId": "CogniteNotification"
    }
}

4. For each property, you can either keep the default space or the space where you created custom views.
5. Save to apply the changes.

Field configuration

tip

The Maintain Field and Feature configurations are currently based on RAW JSON. It's recommended to copy the configuration into a text editor, edit it, and, once finished, paste it back into the configuration modal.

Field Configuration lets you choose which fields to show, how they look in the user interface, and how the user can use the fields. The Field Configuration is a JSON object that contains one key-value pair for each field in the activity view type that should appear in Maintain. The key should be the name of the field in the activity view type, while the value is a JSON object containing the configuration of that field in Maintain.

See the example:

{
    "title": {
        "alias": "Activity Title",
        "displayInTable": 1
    },
    "status": {
        "alias": "Status",
        "displayInTable": 2
    }
}

In the example, Maintain displays two fields in the Activity table, with the “title“ field renamed to “Activity Title“ and “status“ renamed to “Status“. Also, the title should appear before the status.

Further configuration of the individual fields can be done by adding entries to Field Configuration. See the list of the basic configuration properties:

Config key	Description	Type	Default if not set
alias	A string or an object containing a clear field name in different languages	string	Same value as the name of the field in the data model
blacklisted	Define whether this field should be completely excluded from being displayed in the application	boolean	false
displayInGroupDropdown	Define whether this field should be displayed in the group dropdown menu at the top level. You can group all fields under “Show all attributes“, but these are displayed first.	boolean	false
displayInTable	Define whether this field should be displayed in the table by default. The number provided defines the order in which the field will appear. If not provided, the field isn't displayed in the Activity table by default.	number	null
additionalTableField	Define whether this field should display an additional accessory field under it in the Activity table. The value is the name of the field to show in the Activity table.	string	null
approximateDataSize	Define how much space the field will occupy in the Activity table	string: 'small', 'medium' or 'large'	'medium'
displayInGantt	Define whether the value of this field should be displayed under the activity bar in the Gantt lens	boolean	false
displayInFilterMenu	Define whether this field should be displayed by default in the filtering menu sidebar. Note that the user can add fields manually later, but this should be true for “common“ fields the customer may filter on.	boolean	false
displayInSortDropdown	Define whether this field should be displayed in the Sort dropdown	boolean	false
prefix	Enter the prefix to show next to the field value. For example, if the prefix is set to “$“ and the field value for an activity is “5“, the text to appear in the application will be “$5“.	string	null
postfix	Enter the postfix to show next to the field value. For example, if the postfix is set to “$“ and the field value for an activity is “5“, the text to appear in the application will be “5$“.	string	null
decimalPoints	Enter the number of decimal points to show if this is a number field. For example, if the value is “5.55555“ and decimalPoints is set to 2, the value to appear in the application will be “5.56“.	number	null
fieldSubtype	Define the field's subtype. This is used to define how filtering works in this field. Setting to “OPTION“ shows a dropdown list of all existing values. Setting to “FREETEXT“ will let the user filter it by a simple text string. Use freetext for any field where each value is unique, such as ID-type fields.	string: 'FREETEXT', 'OPTION'	'OPTION'
colorCoding	Configures this field to have color coding based on the value. See Color coding configuration.	object	null
colorCodingInGantt	If “colorCoding“ is set, enable coloring Gantt for this field	boolean	false
colorCodingInTable	If “colorCoding“ is set, use coloring on this field in the table	boolean	false
allowFilteringByMultipleValues	On fieldSubtype: "FREETEXT" fields only; enables filtering by multiple values separated by comma	boolean	false

Color coding of fields

You can configure color coding for the Gantt chart and the Activity table. If you've configured color coding for the specific fields, Maintain lets you color-code the Gantt bars. The color coding is defined by providing a specific color for each value of the field. By default, all values without explicit color coding will be gray. You can set the color coding in Field Configuration.

See the example to learn how to configure color coding on a materialStatus field.

{
...
  "materialStatus": {
    ...
    "colorCoding": {
      "OK": {
        "background": "rgba(0, 100, 0, 1)",
        "color": "rgba(0, 255, 0, 1)"
      },
      "MISSING": {
        "background": "rgba(100, 0, 0, 1)",
        "color": "rgba(255, 0, 0, 1)"
      }
    },
    "colorCodingInGantt": true,
    "colorCodingInTable": true
  }
}

If the field value is “OK,” it will be colored green; if it's “MISSING,” it will be colored red. This field will be colored both in the table and the Gantt chart.

Feature configurations

Below are instruction to configure certain optional features of Maintain.

Landing page configuration

You can configure the landing page to show the user's name. Since the name of a user depends on the customer's IdP, the way to format the name for each customer is different. By default, the landing page shows a welcome message without a name. If you set the displayNameRegex property in Feature Configuration to a regular expression with a capture group for “name“, it'll display only the matching substring in the header. For example, if the customer has a "last_name, first_name" format in their IdP, the following configuration can be used to display “Welcome, first_name“:

displayNameRegex: ".*, (?<name>.*)"

The format of the regular expression must follow the JS standard.

Language configuration

Maintain supports multiple languages. When signing in for the first time, you can see a list of available languages. If you need certain languages to be available, set the availableLanguages property in Feature Configuration.

The example shows the setting for the English and German languages.

"availableLanguages": ["en", "de"]

A full list of available languages is a work in progress. Reach out to the Cognite Maintain team for an up-to-date list.

Customer-specific language configuration

By default, Maintain supports localization of native application strings only. Custom strings aren't translated automatically and there are features that require manual translation:

• Naming of fields in the data model. See Field Configuration > alias.

• Naming of fields in the activity creation modal. (Described in the activity creation section below on the “alias“ property)

Time and date configuration

To configure how dates are formatted globally in Maintain, set the following keys under timezoneConfiguration in Feature Configuration:

Config key	Description	Type	Default if not set
startOfWeek	Set the starting day of the week. Possible values: 0 to start the week on Sunday; 1 to start the week on Monday. This affects date picker components in the application and also which day is the first day in the Gantt header on week granularity.	string	1
dateFormat	Set the global date format for dates. See possible formats.	string	“DD/MM/YYYY“
dateTimeFormat	Set the global date format for date and time, for example, where dates and time of the day are shown together. See possible formats.	string	“DD/MM/YYYY HH:mm“

Gantt

The Gantt lens is added by default. To remove the Gantt lens, set "disabled" to true in Feature Configuration:

"ganttConfiguration": { "disabled": true }

Operations

To add operations, set "enabled" to true in Feature Configuration:

"subactivitiesConfiguration": { "enabled": true }

3D and digital twin

The 3D feature is added by default. To remove the functionality, set "disabled" to true in Feature Configuration:

"threeDConfiguration": { "enabled": false }

Basic configuration:

First, 3D configuration requires configuring the customer's 3D models (Locations). You can do this in Maintain > your.Config > Root Location Configuration. You need to make an entry in this JSON object for each location (e.g., a 3D model) that the customer wants to visualize.

Each entry needs to have three entries:

Entry	Description
label	The human-readable name of the location that appears in the application
value	The unique identifier of the site; can be anything as long as it's unique for the project
modelId	The ID of the CDF model for this location

The example shows the configuration for a project that has two locations, Site A and Site B:

{
  "locations": [
    {
      "label": "Site A",
      "value": "SITE_A",
      "modelId": 1234
    },
    {
      "label": "Site B",
      "value": "SITE_B",
      "modelId": 5678
    }
  ]
}

2D and Industrial Canvas

The 2D and Industrial Canvas functionality is added by default. To remove this functionality, set "disabled" to true in Feature Configuration:

"canvasConfiguration": { "disabled": true }

By default, all supported documents ingested into the CDF project can be opened in Maintain. However, additional configuration is required to fully use the 2D features.

Supported document types

Maintain supports the 'application/pdf' MIME type (Multimedia Internet Mail Extensions) documents. Other document types won't appear in the search in Maintain.

note

All files must have an external ID, otherwise, you won't open a file.

Document naming and grouping

Documents can be grouped by their type. By default, documents have the Unknown type. Maintain supports the following types without additional configuration, but other types can be added on request:

Value in “Type“ metadata	Description
LAY	Layout diagram
PID	P&ID
PLT	Plot plans
SLD	Single-line diagrams
UNK	Unknown

note

The document type is used for logical grouping only and doesn't affect how Maintain interacts with documents.

In CDF, the metadata fields for documents in Maintain are Name for the document title and Title for the document description.

Layout

To add layouts, set "enableCustomLayouts" to true in Feature Configuration:

"enableCustomLayouts": true

Also it required presence of attribute activeColorCoding in MaintainLayout view (data model Maintain).

type MaintainLayout {
  ...
  activeColorCoding: String
  ...
  }

Plan Analysis, Budget and Hourly Optimization, and Resources Allocation

To add Plan Analysis and Resources Allocation (contains Budget and Hourly Optiomization), set "enablePlanAnalysis" and "enableResourceAllocation" to true in Feature Configuration:

"cabinetConfiguration": {
  "enablePlanAnalysis": true,
  "enableResourceAllocation": true
}

You can see the bottom panel with Plan Analysis, Budget and Hourly Optimization , and Resources Allocation for the created plans only.

note

To work with Resource Allocation, you need to add values for personHours and numberOfMainResource in the CogniteOperation view when ingesting data in your data model.