Model your asset hierarchy in Splunk IAI

In order to browse your assets and their associated metrics and alarm data in Splunk Industrial Asset Intelligence (IAI), you need to model them in one or more hierarchies. The asset hierarchies provide a structure that you can subsequently use to map your data, making it possible to navigate to and act on the data for a specific asset or group of assets.

You must create each asset hierarchy in the form of a comma-separated values (CSV) file and upload it in Splunk IAI.

Best practices for modeling your assets in Splunk IAI

You may wish to create multiple, more granular asset hierarchy files if either of the following are true:

• You want to apply access controls for different subdivisions of your organization, such as regions or divisions. Each asset hierarchy can be independently mapped to data from a specific index or to multiple indexes. If your Splunk Enterprise administrator divided data into separate indexes to apply granular access controls, you may wish to create a separate asset hierarchy for each set of data.
• You have an area in your organization where the asset structure is likely to change. Once you upload an asset hierarchy, you cannot modify it. Instead, you must delete it and upload a new one. To minimize the effort required to map assets from your data to the new asset hierarchy, restrict the scope of any asset hierarchy files that you are likely to change frequently.

Do not include metrics or alarm data in your asset hierarchy files. You associate data to this hierarchy in a later step, and that data carries with it all the metrics and alarms for each asset.

Create an asset hierarchy CSV

Create one or multiple CSV files to model the assets in your organization.

CSV files must meet the following requirements:

• The header row of the file must reflect your asset levels using the notation L0, L1, L2, L3, L4, L5, L6. The max level is L6. The first level must be L0.
• The CSV file must contain at least two columns and no more than seven columns.
• Asset names must be plain ASCII text with valid UTF-8 characters.
• Asset names within the CSV file cannot contain periods (".") or slashes ("/", "\").
• CSV files cannot contain any parentheses or ampersands.
• CSV files cannot contain spaces before or after commas that separate values. For example, node 1,node 2 is well-formed, but node 1, node 2 is not.
• The maximum file size must not exceed 52 MB.
• CSV files cannot have "\r" line endings (OSX 9 or earlier).
• The CSV file cannot have the same name as another CSV file you already uploaded.

In Windows, you might encounter an issue with incompatible line return characters in your CSV file. These characters result in a Windows wait cursor, which does not ever finish. To resolve this issue, cancel the existing upload, and try converting the CSV file to a supported line return encoding type. You can do this by opening the file in a text reader and saving it with a new name, and choosing UNIX line breaks.

The following is an example of an asset hierarchy CSV file:

L0,L1,L2,L3
East,Alpha Plant,Line 1,Wood Grinder Nexus3 A908
East,Alpha Plant,Line 1,Pulp Oven s009
East,Alpha Plant,Line 1,Bleacher1
East,Alpha Plant,Line 1,Press 1
East,Alpha Plant,Line 2,Wood Grinder Nexus3 A908
East,Alpha Plant,Line 2,Pulp Oven s009
East,Alpha Plant,Line 2,Bleacher2
East,Alpha Plant,Line 2,Press 2
East,Beta Plant,Pilot Line,Wood Grinder Nexus3 A908
East,Beta Plant,Pilot Line,Pulp Oven s009
East,Beta Plant,Pilot Line,Bleacher3
East,Beta Plant,Pilot Line,Press 3
East,Beta Plant,Pilot Line,Dryer
West,Delta Plant,Line 1,Wood Grinder Nexus3 A908
West,Delta Plant,Line 1,Pulp Oven s009
West,Delta Plant,Line 1,Bleacher4
West,Delta Plant,Line 1,Press 4

Assets in the hierarchy are not required to have unique names, but the full path to any asset (L0.L1.L2.L3.etc) must be unique within a hierarchy.

Upload an asset hierarchy

1. Log in to Splunk Web and access Splunk Industrial Asset Intelligence.
2. Click the Configure gear icon.
3. Click Add.
4. Enter a Name and an optional Description.
5. Drag and drop the file you want to upload to the Drop your file here area on the page, or click Browse to navigate to the file.
6. Review the displayed preview to ensure the hierarchy structure matches your expectations. The preview shows a maximum of 500 rows.
7. Check the rows of the preview content to check that your asset names do not contain periods, parentheses, ampersands, slashes, or any non UTF-8 characters.
8. Review the preview panel on the right by expanding the tree structure to check that the hierarchy nodes are organized correctly.
   If you need to make adjustments to your file, make the needed corrections to your CSV, and then click Not the right file? Upload a new one to upload and preview the revised file.
9. When the preview looks correct, click Add.

Edit an asset hierarchy

If you need to edit the name or description of an asset hierarchy, perform the following steps:

1. Click the Configure gear icon.
2. Click the Asset Hierarchies tab.
3. In the row for the asset hierarchy you want to edit, click Edit under the Actions column.
4. Make changes to the name or description, then click Save.

You cannot modify the contents of an asset hierarchy after you have uploaded it in Splunk IAI. To change the structure of your hierarchy, delete the hierarchy and upload a new one.

Delete an asset hierarchy

As an IAI admin, you can delete asset hierarchies.

Deleting an asset hierarchy is irreversible. If the asset hierarchy is being used in one or more operations, you can lose data.

The following consequences can happen when you delete an asset hierarchy:

• If you associated data to the asset hierarchy, deleting the asset hierarchy also deletes the data association logic.
• If you associated this asset hierarchy with one or more operations, the following is also true within all those operations:
  • If you created calculated metrics for an asset in this asset hierarchy, deleting the asset hierarchy also deletes those metrics.
  • If you created alerts for a metric in this asset hierarchy, deleting the asset hierarchy also deletes those alerts.
  • If you created monitor views that use metrics from assets in this asset hierarchy, deleting the asset hierarchy causes the widgets for those metrics to display with a message "This metric is not available."
  • If you created calculated metrics in a group or on an asset from another asset hierarchy, and that calculated metric uses metrics from assets in this asset hierarchy, deleting the asset hierarchy causes those metrics to fail.

To delete an asset hierarchy:

1. Click the Configure gear icon.
2. Click the Asset Hierarchies tab.
3. In the row for the asset hierarchy that you want to delete, click Delete.
4. Check the boxes to confirm that you understand the consequences of deleting the asset hierarchy.
5. Click Delete.