Configure InField
The features described in this section are currently in beta testing and are subject to change.
Proper planning is crucial to setting up the InField application. This section helps you plan and configure the source data and the Cognite Data Fusion (CDF) project that will power the application and describes how to set up assets and visualize data in InField. You can also use the CDF Toolkit to use pre-built configurations to set up InField.
Before you start
Make sure you have the following:
- A project registered in the CDF portal application.
- The CDF API and the CDF portal application registered in Microsoft Entra ID(formerly Azure Active Directory (AD)) and Microsoft Entra ID and CDF groups set up to control access to CDF data.
- Data in the CDF project, a classic asset hierarchy must be in place.
- Access to the InField application. A Cognite or CDF project administrator can request access and activate the project in Cognite InField. Submit a request.
- URLs in your allowlist.
Set up access
You can use your existing identity provider (IdP) framework to manage access to InField 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 thus give different access rights to each group.
Create admin group
Create a group of users who can configure the InField application across all locations.
- Go to CDF > Manage > Manage access.
- Create a group and name it
applications-configuration
. - Give
read
andwrite
access to all capabilities with the scopeAll
, or have the minimum set of capabilities.
Capability type | Action | Scope | Description |
---|---|---|---|
Assets | assets: read | All | View asset data from the CDF project that InField runs on top of. |
Groups | groups: read , groups: list | All | For InField administrators to grant access to users. |
3D | 3D: read | All | Upload 3D models to display in InField. |
Data sets | datasets: read | All | Get data from work order management system, such as SAP, and work orders. |
Data models | dataModel: read | All | Organize and structure data. |
Data model instances | dataModelInstance:read | All | Access data organized in data models. |
Data model instances | dataModelInstance:write | cognite_app_data , APM_Config | Access and edit data organized in data models and spaces. |
Create standard user groups
Create groups of users who can view checklists, administer checklists and templates, and work with checklists in the field. You can create similar groups for different locations. The groups can have the same capabilities but different access based on the group name.
Group names are suggestions and can differ from user to user.
Read only access
Create a group of users who can view but not edit checklists. You can name the group infield_dev_location_viewers
, where dev
is the InField environment, and location
is the location that the group will have access to.
Capability type | Action | Scope | Description |
---|---|---|---|
Groups | groups: read , groups: list | All | View user groups. |
Assets | assets: read | asset_datasets | View and analyze asset details. |
3D | 3D: read | threed_datasets | View and analyze 3D models. |
Files | files: read | files_datasets, infield_app_data_dataset | View and analyze images and files. |
Relationships | relationships: read | relationship_datasets | View relationships between assets. |
Time series | timeseries: read | timeseries_datasets, infield_app_data_dataset | View and analyze time series data. |
Data models | dataModel: read | APM_Config , cdf_apm , cdf_infield , cdf_core , cdf_apps_shared , apm_source_datamodel_space - the space where the APM_SourceData model is defined | View and analyze the data created in InField. |
Data model instances | dataModelInstance:read | APM_Config , cdf_apm , cognite_app_data , location_app_data_space , location_source_data_space | View and analyze the data created in InField. |
Data model instances | dataModelInstance:write | cognite_app_data | Access and edit data organized in data models and spaces. |
Read and write access
Create a group of users who can administer checklists and templates and work with checklists in the field. This can be a single group for all users or 3 different groups. If you create 3 separate groups, you can use the following naming suggestions.
Name | Description |
---|---|
infield_dev_location_checklist_admins | Users in this group can create, update, delete, and approve checklists in the specified location (location ) and environment (dev ). |
infield_dev_location_template_admins | Users in this group can create, update, and delete templates in the specified location (location ) and environment (dev ). |
infield_dev_location_checklist_users | Users in this group can work with checklists and create observations in the specified location (location ) and environment (dev ). |
To create a group of users who can view and edit checklists:
- Add read only capabilities.
- Add the following write capabilities.
Capability type | Action | Scope | Description |
---|---|---|---|
Files | files: write | infield_app_data_dataset | View and edit documents and files. |
Relationships | relationships: write | infield_app_data_dataset | Relationships represent connections between pairs of CDF resources. |
Data model instances | dataModelInstance:write | location_app_data_space | Access and edit data organized in data models and spaces. |
To add checklist and template admins to your root location:
- In
InField, go to Application configuration > Root Location > Edit location > Template/checklist admins. - Select the corresponding group for each dropdown and save the configuration.
Create data modeling spaces
InField has two ways of storing assets: classic asset hierarchy and asset data modeling. You need to create at least 5 spaces to store your data and data models.
Space name | Description |
---|---|
cognite_app_data | This space holds user data, such as user profiles. |
APM_Config | This space holds configurations in Asset Performance Management (APM). |
AMP_SourceData | This space holds the schemas/data models for the data types that should be stored in the yourRootLocation_source_data space. |
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 InField (from checklists and templates) for a particular location. |
ApmAppData | You don't need to set up or change this space. ApmAppData is a system data model that's present in all projects by default. The data model has the System tag. |
Create new yourRootLocation_source_data
and yourRootLocation_app_data
spaces for each root location you have.
You can create spaces in the following ways:
- All 5 spaces with the Cognite Python SDK.
- 3 spaces with the CDF API and 2 spaces manually in the Cognite Data Fusion (CDF) or automatically by using the script.
Spaces created with SDK
You can create all 5 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", "APM_SourceData", "APM_Config", "cognite_app_data"]
# Apply spaces
for space_name in spaces_to_create:
client.data_modeling.spaces.apply(SpaceApply(space=space_name))
Spaces created with API
Create the following 3 spaces using the API endpoint:
cognite_app_data
yourRootLocation_source_data
yourRootLocation_app_data
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
.
APM_Config
and APM_SourceData
are the spaces that you can create manually in CDF or automatically by running the script. You create these spaces by creating corresponding data models.
To create the spaces manually:
- Go to CDF > Data management > Data models > Create data model.
- Name the data model
APM_Config
and add a description if needed. - Select From scratch > Space name > + Create new space.
- Name the space
APM_Config
.
Follow the same steps to create the APM_SourceData
data model and space.
To create the spaces automatically:
- Run the scripts in the repository for
APM_Config
andAPM_SourceData
to automatically deploy these data models for your project.
Add scheduling function
With the scheduling function, users can create checklists from template tasks based on the schedule.
To add the scheduling function:
- Go to the GitHub repository and follow the manual deployment process instructions.
The scheduling functionality in InField follows Google Calendar behavior with a few exceptions. See how to schedule checklists from template tasks in the InField application.
AWS cluster
If you are on the AWS cluster and you want to enable file upload to it, add your project to the feature flag.
Configure APM_Config
in CDF
A data model is an abstract model that organizes data elements and standardizes how they relate to one another and the properties of real-world entities. The CDF data model collects industrial data by resource types that let you define the data elements, specify their attributes, and model the relationships between them. The different resource types are used to both store and organize data. Read more about resource types.
To create the APM_Config
model and the corresponding space:
- Go to CDF > Data management > Explore > Model your data > APM_Config.
- In the Editor , delete the existing code snippet and paste the
APM_Config
model data code snippet.
APM_Config model
type APM_Config @view (version: "1"){
name: String
appDataSpaceId: String
appDataSpaceVersion: String
customerDataSpaceId: String
customerDataSpaceVersion: String
featureConfiguration: JSONObject
fieldConfiguration: JSONObject
rootLocationsConfiguration: JSONObject
isDefault: Boolean
}
Populate the APM_SourceData
model only after you've set up your root location in the InField application.
Create transformation
Populate your locations with asset data. As you already have a classic asset hierarchy in place, you can use transformations to convert this data into assets in data modeling.
Read about data transformation and how to transform data in CDF.
First, create a transformation via the API or SDK since certain functionality is unavailable in CDF.
For the code snippets, change the key for the instanceSpace
attribute to yourRootLocation_source_data
you created earlier. Ensure the parameters in the view
object remain unchanged.
If you're using Postman, replace {cluster}
and {your_project}
with the actual project name.
API code snippet
{
"items": [
{
"name": "migrate-classic-asset-to-core-asset",
"query": "/* MAPPING_MODE_ENABLED: false */\n/* {\"version\":1,\"sourceType\":\"clean\",\"mappings\":[{\"from\":\"externalId\",\"to\":\"externalId\",\"asType\":\"STRING\"},{\"from\":\"\",\"to\":\"parent\",\"asType\":\"STRUCT<`space`:STRING, `externalId`:STRING>\"},{\"from\":\"\",\"to\":\"source\",\"asType\":\"STRING\"},{\"from\":\"\",\"to\":\"root\",\"asType\":\"STRUCT<`space`:STRING, `externalId`:STRING>\"},{\"from\":\"\",\"to\":\"description\",\"asType\":\"STRING\"},{\"from\":\"\",\"to\":\"labels\",\"asType\":\"ARRAY<STRING>\"},{\"from\":\"\",\"to\":\"title\",\"asType\":\"STRING\"},{\"from\":\"\",\"to\":\"sourceId\",\"asType\":\"STRING\"}],\"sourceLevel1\":\"_cdf\",\"sourceLevel2\":\"assets\"} */\nselect\n cast(asset.externalId as STRING) as externalId,\n \n (case \n when isnull(asset.parentExternalId) then null\n else node_reference('location_source_data_instance_space', asset.parentExternalId)\n end )as parent,\n cast(\"CDF Classic\" as STRING) as source,\n node_reference('location_source_data_instance_space', cast(rootAsset.externalId as STRING)) as root,\n cast(asset.description as STRING) as description,\n cast(asset.name as STRING) as title,\n cast(asset.externalId as STRING) as sourceId\nfrom\n cdf_assetSubtree('configured_location_externalId') as asset \n inner join cdf_assetSubtree('configured_location_externalId') as rootAsset on asset.rootId = rootAsset.id ",
"destination": {
"view": {
"space": "cdf_core",
"externalId": "Asset",
"version": "v1"
},
"instanceSpace": "location_source_data_instance_space",
"type": "nodes"
},
"conflictMode": "upsert",
"isPublic": true,
"externalId": "tr-migrate-classic-asset-to-core-asset",
"ignoreNullFields": true
}
]
}
SDK code snippet
import json
_body = {
"items": [
{
"name": "migrate-classic-asset-to-core-asset",
"query": "/* MAPPING_MODE_ENABLED: false */\n/* {\"version\":1,\"sourceType\":\"clean\",\"mappings\":[{\"from\":\"externalId\",\"to\":\"externalId\",\"asType\":\"STRING\"},{\"from\":\"\",\"to\":\"parent\",\"asType\":\"STRUCT<`space`:STRING, `externalId`:STRING>\"},{\"from\":\"\",\"to\":\"source\",\"asType\":\"STRING\"},{\"from\":\"\",\"to\":\"root\",\"asType\":\"STRUCT<`space`:STRING, `externalId`:STRING>\"},{\"from\":\"\",\"to\":\"description\",\"asType\":\"STRING\"},{\"from\":\"\",\"to\":\"labels\",\"asType\":\"ARRAY<STRING>\"},{\"from\":\"\",\"to\":\"title\",\"asType\":\"STRING\"},{\"from\":\"\",\"to\":\"sourceId\",\"asType\":\"STRING\"}],\"sourceLevel1\":\"_cdf\",\"sourceLevel2\":\"assets\"} */\nselect\n cast(asset.externalId as STRING) as externalId,\n \n (case \n when isnull(asset.parentExternalId) then null\n else node_reference('location_source_data_instance_space', asset.parentExternalId)\n end )as parent,\n cast(\"CDF Classic\" as STRING) as source,\n node_reference('location_source_data_instance_space', cast(rootAsset.externalId as STRING)) as root,\n cast(asset.description as STRING) as description,\n cast(asset.name as STRING) as title,\n cast(asset.externalId as STRING) as sourceId\nfrom\n cdf_assetSubtree('configured_location_externalId') as asset \n inner join cdf_assetSubtree('configured_location_externalId') as rootAsset on asset.rootId = rootAsset.id ",
"destination": {
"view": {
"space": "cdf_core",
"externalId": "Asset",
"version": "v1"
},
"instanceSpace": "location_source_data_instance_space",
"type": "nodes"
},
"conflictMode": "upsert",
"isPublic": True,
"externalId": "tr-2-migrate-classic-asset-to-core-asset",
"ignoreNullFields": True
}
]
}
body = json.dumps(_body, ensure_ascii=False, indent=2)
print(body)
client.post("/api/v1/projects/{sdf-project}/transformations", json=_body)
Once you've created the transformation, do the following:
- In CDF, go to Integrate > Transform data, and then select the
migrate-classic-asset-to-core-asset
transformation. - In the SQL editor, you need to switch the
location_source_data_instance_space
with yourlocation_space
(the space you created via the API in the beginning), and theconfigured_location_externalId
with theexternalId
of your root asset. - Select Preview to test the transformation.
- Comment out parent and root direct relation since you don't have assets yet to create relations.
- Select Run if the populated table looks correct.
- Include parent and root direct relation and run the transformation again.
When you run a transformation, make sure you create parents before children. It's also possible to create two transformations, one that creates the assets without direct relationships and then a second transformation that just updates the assets with these relationships.
Configure root location
The users need to have admin rights to be able to work with the root location configuration.
Root location is a root asset that's at the top of the asset hierarchy. The root asset is a digital representation of a site, such as an oil platform, a plant, or an installation. Each site in InField should have a root location. For each location you want to be available in InField, complete the detailed configuration to visualize the data in the InField application.
- Sign in to
InField, select Application configuration (⚙) > Root Location > Add Root Location. - Select the root asset name or enter the location external ID and select Add.
- Select Edit asset to set up some asset cards for the asset overview page and complete location configuration.
![Root location configuration](https://apps-cdn.cogniteapp.com/@cognite/docs-portal-images/1.0.0/images/cdf/configure/infield/location_config.png)
Features
Configure what features your users can access and what asset details they can see in the asset explorer.
- In the Features section, select what features to show in the application for the users in each location. Turn the features on or off to show or hide them. By default, the users can access all features except Observations.
Feature | Description |
---|---|
Templates and checklists | Create templates, create checklists out of a template or its tasks, assign checklists to disciplines, view and analyze the collected data on the Overview page. |
Work orders | Create checklists from a work order or its tasks that come from a work management system and view and analyze the collected data on the Overview page. |
Observations | Create observations on malfunctioning equipment or record other issues. When this feature is turned on, you can customize the fields on the observation form on the Observations tab. Provide external IDs for the Notifications and Attachments endpoints. You'll have these IDs when you create an SAP instance in the new write-back service. |
Write-back to SAP | Send an observation copy as a Notification to SAP. Make sure that you provide external IDs for the Notifications and Attachments endpoints. |
-
In the Asset explorer section, select what cards to show for the assets in each location. Turn the cards on or off to show or hide them for the users.
-
Save configuration.
3D
Set up 3D models for your location to view them on the 3D card on the asset overview page. To display a 3D model on the 3D card:
- Under Full weight model, select Add 3d model. The 3D model must already exist in CDF. Learn more about 3D models.
If your 3D model has asset mappings, the 3D viewer will automatically display the selected asset.
You can add several 3D models per root location. Only models with asset mappings containing the current asset will be shown, and if there are several, the user can select one in the 3D viewer.
The lightweight model is a low-resolution 3D model shown on the 3D card, which can be used to locate the current asset. Configuring such models isn't recommended since they require manual creation and provide limited value.
Data set
Add the data set ID from a previously created data set that stores data (time series and files) created in InField. The time series created in InField gets a metadata field (source
=APP
) to identify its origin.
When adding a numerical reading in InField, you can connect it to the time series created directly in the application and the time series stored in the data set for the selected location.
Optional. Checklist and template admins
Specify groups of users who can create and edit templates (template admins) and who can view and approve checklists (checklist admins). If you don't select any group, all users will have the same access.
AppData Instance Space
Enter the name of the space you created (yourRootLocation_app_data
) to hold data on templates, checklists, and observations created in the application.
SourceData Instance Space
Enter the name of the space you created (yourRootLocation_source_data
) to hold data on assets, work orders, notifications, and other APM-related types.
To display work orders on the Work orders card
- Upload the work orders into the configured space. Make sure that:
assetExternalId
is set to the correct assetcloneOf
=null
source
is NOTAPP
space
=yourRootLocation_source_data
You can also configure how users see work orders data on the Work orders card on the asset overview page.
- Return to the Application configuration page and select Activities.
- Add fields to filter on and add accepted values. The work orders on the card will be filtered based on the values provided. For example, if you set the filter to show work orders based on their status with values RDEX or VARX, then the work order card will show work orders with the RDEX or VARX status. To view all work orders, select Open.
Configure custom data filters
Custom data filtering lets you configure locations to see data from several asset subtrees and root assets in asset hierarchy and from data modeling service. You can filter on general data that includes all data types. You can also filter individually on assets, time series, and files.
To get access to data filtering:
- In InField, go to Application configuration > Root location > Edit asset > Custom data filtering.
- Copy the external ID APP_CONFIG_V2 for a new version of the
APM_Config
model and select Create. This will create a copy of the existing model and add new fields to allow custom data filtering. All data configured in APM_Config will be available in the new instance.
Make sure to copy the external ID APP_CONFIG_V2. You'll need this ID to delete the new configuration from CDF if something goes wrong. When you delete the new configuration, the original configuration will automatically revert all changes.
To add assets to filter data in asset hierarchy:
- Under General, add external IDs of the assets you want to filter on in addition to your root location. Make sure your root location ID is included in the comma-separated list. Assets, time series, and files will inherit the provided IDs.
- Under Assets, add prefixes of the external IDs of the assets that will be used to filter assets.
- Under Time series, add prefixes of the external IDs of the assets that will be used to filter time series.
- In the Data set IDs field, provide the data set ID that holds time series and files created in InField and add more data set IDs to filter time series. If you don't want to filter on data sets, leave the field empty.
- Under Files, add prefixes of the external IDs of the assets that will be used to filter files.
- In the Data set IDs field, provide the data set ID that holds time series and files created in InField and add more data set IDs to filter time series. If you don't want to filter on data sets, leave the field empty.
To add assets to filter data in data modeling service:
- Under General, add external IDs of the assets you want to filter on in addition to your default root location. Make sure your root location and the root locations that you add belong to the same space.