ContextHub - Asset structure

The asset tree

Your asset tree can be found in the asset browser on TrendHub. 

1. Select the tags icon, and click on the "Search tags & attributes" button located next to the Hub Switcher in the unified top bar. 
2. Look to the drop down menu that opens, and click on the "Assets" option. 

The asset root nodes that have been published or activated will display in the drop down.

The root node is the starting node of an asset path. The path can be made up of many branches and nodes that leads eventually to the assets or attributes of the structure, for example; temperature or concentration. 

This asset browser is also located in ContextHub and is made available when adding a component to a newly created context item or a newly created context view filter. 

Asset tree structure

The following is a typical example of an asset tree in TrendMiner:

• Houston  (root node asset)
  • Reactor 1 (standard node sub-asset)
    • Concentration (attribute - leaf node)
    • Temperature
    • Level

Asset structure csv import (admin option)

If you are without a specialized tool like OSIsoft PI AF, and want to set up an asset structure, you can use the built in asset structure CSV import inside ContextHub. You can define your structure inside a ready made CSV file available for download. 

1. Select ContextHub using the hubswitch
2. Select "Config"
3. Select "Asset structure"
4. Click on the Add asset structure option

An "Add asset structure" side panel opens from the right of the screen. Download the example file made available in the side panel.

The following is the example file, opened with a spreadsheet tool:

General rules when laying out the structure in CSV

• The parent of a node (single row) should be defined above its children
• The markup of the file requires you to use the CSV markup with a comma (,) as a separator and all values optionally quoted with “
• Encoding must be UTF-8 
• The path is the full path of the asset. It must include the name. And the name must be consistent in use. This means consistent spelling and case use. 
• When uploading a completely new AF structure, the source-field must be empty. You will see that after the initial upload and when the AF-tree is created, the source-field will be automatically filled in when downloading the AF-structure. More Details can be found in the section "Updating the CSV asset structure" 

Updating the CSV asset structure

IMPORTANT!!! From the Asset structure config screen (ContextHub → Config → Asset structure) download your current asset structure. This way your list of assets and attributes will have a column called ‘id’. This id is the unique identifier of the asset or attributes in the TrendMiner system. This way, we’ll know that when you update one of the rows in your csv-file, to which asset in the TrendMiner system you are referring to. Also the source column is filled in now.

To update a row, make sure the ‘id’ column of your row is filled in. Here you can edit the path,name, description, type, template, and tag. The source column cannot be updated.

Note: When updating the name of an item, you also need to update the path.

For new entries in the structure, leave the ‘id’ field empty. In the source field, you need to copy paste the source id from the other rows. This id is the same in all rows and unique per asset tree.

To delete entries, remove the rows from the CSV file to delete the asset or attribute from the TrendMiner asset structure.

Mandatory columns in the csv-file:

• Path
• Name
• Type (can be ASSET (no tag data reference), ATTRIBUTE (with tag data reference)
• Tag with historian prefix (if type = ATTRIBUTE) (eg: [PI18]BA:LEVEL.1)
• Source: This is the identifier of the asset csv tree. It has to be present on every line

Note: ID is mandatory for updates, otherwise it will try to create the asset and an error will be returned: Asset with path {0} already exists with ID {1}. You must use this ID if you want to re-enable the node.

Note: The prefix is only needed when we have multiple historians. If there's only one, the prefix is not needed.

Note: The source is mandatory when updating. When adding a new asset structure, it is mandatory to be empty.

Once your CSV file has been populated: 

1. Fill in a name for your asset structure.
2. Add the file by clicking on the "Add attachment" button in the  "Add asset structure" side panel. Select the file. 
3. Click the "Add" button at the base of the panel. Your new asset structure is now added to your asset structure menu in ContextHub. You will receive a notification when it's done. If there was something wrong with the file, an error file will be generated with error messages for specific rows.
4. To activate the newly uploaded asset structure, click on the "Publish asset structure for everyone with permissions" switch. 
5. Click the save button.

Now published, your new asset structure is available in the platform asset browser when opened. Unpublished asset structures are only available for admins.

Note: Multiple uploaded asset structures can be published and made available in the asset browser at any time. 

To reconfigure your asset structure: 

1. Click on the three vertical dots located to the right of each asset structure row in the ContextHub. A small drop down menu appears. 
2. Select "Configure asset structure". A side panel opens providing the CSV details of your asset structure.
3. Click on the small clock located right of the "Download" button. 

A "History" panel will open. This panel will list the uploads for this asset structure, associated times of uploads and whether it was successfully uploaded. Error files can be consulted here. You can close this panel using the "Close history" button at the base of the panel.

To update the asset structure, simply 

1. Alter the CSV file as necessary (see above).
2. Add the file to the side panel via the "Add attachment" option. 
3. Click the "Save" button.

Templates and the cross asset value based search

To indicate that different assets are similar and contain the same set of attributes, TrendMiner uses templates in the asset structure.

In the CSV file you can add templates by adding them in the ‘template’ column. This displays them next to your assets in the asset browser and helps our searches and algorithms to give back better results in the future.

The cross asset value based search is a TrendMiner search option that enables you to explore through similar assets and attributes that are predefined as part of a template. 

Having defined your templates and grouped your assets and attributes within the template column, you will be able to search through your assets and attributes in the form of groups, as opposed to individual datasets. 

The image directly below is an example of an asset file structure that contains the template name "BA Reactor". This particular template groups reactors 1, 2 and 3. Traditionally through the value based search you would need to save each individual reactor search for a particular value of interest, to then compare and contrast. With the cross asset value based search you can easily search through all reactor data by ensuring at the description level you group each reactor under the template, in this case, BA reactor.

Note: The created template name must be consistent in its use. This means consistent spelling and case use.

Asset tree builder - As of 2023.R1.0 onwards

The asset tree builder, part of the Digital Twin Manager, provides functionality to build new or edit existing (imported by a CSV) asset hierarchies in TrendMiner. It can be found in the Platform Configuration -> Asset structure -> Add asset structure and then under “Configure via” selecting the option “Asset tree builder”.

Then select a name for the asset structure that you want to build and press on "Continue”.

In the “Asset tree builder” you can configure your very own asset structures, inside TrendMiner. You can start by adding a node, which is done by entering a node name and clicking on the plus button.

Once done, a new node should appear as shown below.

Time series data can be attached to a node. This is done by using the search bar on the right side to find the desired time series entity, and then by drag and drop onto a specified node. Only one time series entity can be attached to a node.

A node can have a “Description”, which could be added by clicking on the description placeholder, situated just under a node’s name.

Operations with a node:

MOVE
When you click on the move button - you will be moving the node to a selected node in the asset structure.

After clicking the “Move” button, a side navigation panel, where you can view the asset structure and select a node to move to, will appear.

Note: Any child structure associated with the initially selected node will be persisted.

As with the example below, the node with name “Child node of child node” was moved from being a child node of the node with name “Child Node” to the node with name “Child node of child node 2”.

Note: You cannot move a node onto itself.

DELETE
Delete a selected node and all its descendants or choose to delete the specified node and move all its descendants onto the current level. The structure of the descendants will be preserved.

If you choose to “Delete node and move descendants here”, you would be presented with an asset structure as shown below:

If you choose to delete the node and all of its descendants, you will see the following:

Note: The root Node cannot be deleted.

GO ONE LEVEL DEEPER
Navigate one level deeper into the Asset hierarchy, by clicking the right cursor button on a node of interest:

Note: The Asset Tree Builder can be used to edit already imported CSV asset structures. You can use this feature by selecting “Edit asset structure” on an existing asset structure.

Note: The changes made to the Asset hierarchy are auto saved.