tw_tax_import

Use the tw_tax_import utility to import custom taxonomy files into the current taxonomy.

Storage and modification of the taxonomy

Important

In earlier releases, the taxonomy definitions were configured by using XML files in the installed and custom directories. Any faulty change to the XML file might break the entire taxonomy. We moved to JSON for easier management of taxonomy definitions.

Starting with BMC Discovery version 22.1, JSON-formatted taxonomy files take precedence over the XML files of the same name. The directories are parsed in the existing order (installed before customization), and the files contained in these directories are parsed in alphabetical order, with numbers before letters. This order is important because later definitions for the taxonomy override those loaded earlier.

The capabilities of JSON taxonomy are as follows:

UI visibility when adding a new attribute to the node.
UI visibility when adding a new relationship to the node.

The restrictions of JSON taxonomy are as follows:

Already existing attributes, relationships, and nodes cannot be overridden.
To augment a node, a Detail-node creating is preferred over taxonomy extension.

The advantages of JSON taxonomy are as follows:

Independent editing of specific elements.
Quick search for taxonomy elements.
Readability and simplified structure.
Simplified debugging due to changes in specific nodes.

Importing customized taxonomy definitions

Info

The tw_tax_import utility covers only customization of BMC Helix Discovery items. To customize BMC Helix CMDB items, you need to modify extension mappings. To review the standard CDM mapping and understand how to extend it, see Default-CDM-Mapping.

The standard base taxonomy files are contained in the /usr/tideway/data/installed/taxonomy/00taxonomy directory.

In almost all circumstances you should not need to supply any additional parameters. If you do need to customize the taxonomy, perform these steps:

In the /usr/tideway/data/custom/taxonomy/ directory, create custom subfolders that contain custom JSON files with a sensible naming convention (examples: 10my_extensions and host_extension.node correspondingly).
Load all files by using the tw_tax_import command.

The following table describes options for the tw_tax_import command:

For a detailed scenario of custom JSON taxonomy, see User example.

To extend taxonomy for the Host node

The following example shows the steps for extending the Host node with a custom_item attribute that should be displayed after hostname on the Host node page in BMC Helix Discovery.

From the /usr/tideway/data/custom/taxonomy/10extension/Host_extended.node directory, open the Host.node file and familiarize yourself with the structure of the standard taxonomy definition.
In any text editor, start by defining what is the node kind. In this example, the extension should start with the following lines:
Custom JSON taxonomy file
{
"kind": "Host",
In the attributes section, define the custom_item attribute. In the following example, the name, description, ui_show_if_unset, and label attributes are added:

Custom JSON taxonomy file with an additional attribute

{
   "kind": "Host",

   "attributes": [
       {
           "name": "custom_item",
           "description": "Test custom item",
           "flags": [
               "ui_show_if_unset"
            ],
           "label": "Custom attribute"
       }
     ],

4. (Optional) You can also specify the location of the custom_item attribute by editing the lists section. In this example, we want the custom_item attribute to be displayed after the hostname. For more information about the attribute location options, see Adjusting customized and existing taxonomy definitions.

Custom JSON taxonomy file with custom attribute positioning

{
   "kind": "Host",

   "attributes": [
       {
           "name": "custom_item",
           "description": "Test custom item",
           "flags": [
               "ui_show_if_unset"
            ],
           "label": "Custom attribute"
       }
    ],
   "lists": {
       "node": [
           "!AFTER:hostname",
           "custom_name"
        ]
   }
}

5. Save the file with your custom taxonomy.

6. In the /usr/tideway/data/custom/taxonomy directory, create your subfolder and add your file with the custom taxonomy.

7. Run the tw_tax_import utility.

Your custom taxonomy is merged with the existing taxonomy.

File names and directory structure

Each role, node, and relationship definition is a single file containing a JSON object (dictionary). The file can have any name, but must match the name of the object kind that it contains. Each file must have the appropriate file extension.

The following table shows supported file extensions:

Extension	Kind	Example
.role	Role	Client.role
.node	Node	Host.node
.rel	Relationship	Communication.rel

Attribute flags

The following table shows flags that each attribute of the node can have:

Name	Description
key	The attribute is the key for the node.
optional	The attribute is optional.
expected	The attribute is expected.
nocompare	Ignore the attribute in comparison operations.
system	A system-maintained attribute.
nodup	The list attribute should contain no duplicates.
ui_required	The attribute is required when creating or editing.
ui_no_create	The attribute cannot be set when creating.
ui_no_edit	The attribute cannot be edited.
ui_show_if_unset	Show the attribute even if the value is unset.
ui_hide	The attribute is hidden in the UI.
no_dq_warning	Suppress the error when the optional attribute is missing.
ui_hide_dp	Hide data provenance in the UI.
ui_compare	Enables data comparison in the UI.
ui_plugin	Use the plugin to show the attribute value.
deprecated	The attribute is deprecated and should no longer be populated or used.

Display relationships (Multi-hop traversals)

Use the following display relationship definitions to perform multi-hop traversals to show related nodes:

Name	Description	Type
name	The name of the display relationship.	string
description	The description of the display relationships.	string
traversals	A list of traversal specifications. Each entry is a 4-part role:rel:role:node value defining a traversal.	list
label	The default English label.	string

Example of a traversal display relationship

{
    "name": "edge_connectivity",
    "description": "Network devices this host is connected to",
    "traversals": [
        "DeviceWithInterface:DeviceInterface:InterfaceOfDevice:NetworkInterface",
        "EdgeClient:NetworkLink:EdgeDevice:NetworkInterface",
        "InterfaceOfDevice:DeviceInterface:DeviceWithInterface:NetworkDevice"
     ],
    "label": "Network Devices"
}

Field ordering lists

Field ordering lists are the lists that the object contains. Each list defines the order of attributes, relationships, expressions, and displays relationships to be shown under a specific circumstance. The following table shows the core field lists:

Name	Usage
node	The primary node view.
summary	The default summary fields used in search results.
inline_summary	The summary used when relationships are shown in-line in a node view.
query_builder	The fields shown by default in the query builder.
report_medium_detail	The fields shown in less detailed reports.
report_high_details	The fields shown in more detailed reports.

Adjusting customized and existing taxonomy definitions

Custom entries or attributes defined in the field lists are appended to the existing list by default. In the lists section, you can change the insert position for fields by using the defined directives. Before applying the following directives, ensure that you read them carefully:

!BEGIN — Insert at the start of the field list.
!END — Insert at the end of the field list.
!AFTER:name — Insert after the named field.
!BEFORE:name — Insert before the named field.

Sample positioning of custom taxonomy definitions

"node" : [

    "!BEGIN",

  "attribute1",

    "!AFTER:hostname",

    "attribute2",

    "attribute3",

    "!BEFORE:DeviceWithInterface:DeviceInterface:InterfaceOfDevice:NetworkInterface",

    "attribute4",

    "attribute5",

    "!END",

    "attribute6"
]

Relationships

Relationship kinds have the same values as node kinds with the following additions:

Name	Description	Type
specs	The list of relationship specifications.	list
labels	The list of relationship labels.	object

Relationship specifications

Each item in the specification list is a pair of objects. Each object has the following keys and values:

Name	Description	Type	Notes
role	The name of the role kind.	string	Required and must be a defined role kind.
flags	List of flags.	list of strings	N/A
options	Object mapping options names to values.	object	N/A
description	A string describing the end node, as seen from the other end.	string	Can contain Python format strings {from_kind}, {from_plural}, {to_kind} and {to_plural} that expand to the en_GB translations of the node kind.
translations	An object that maps a locale to a translated label for the end node.	object	Can contain Python format strings {from_kind}, {from_plural}, {to_kind} and {to_plural} that expand to the corresponding locale's translations of the node kind.
nodes	A list of node kinds.	list	Each entry must be a defined node kind (string) or an object.
relationships	A list of relationship kinds.	list	Each entry must be a defined relationship kind (string) or an object.

Specification objects

If the relationship spec needs flags or options, an object can be used instead of a string, with the following keys and values:

Name	Description	Type	Notes
kind	The name of the node or relationship kind.	string	Required.
flags	List of flags.	list of strings	Overrides the flags set at the role level.
options	Object mapping options names to values.	object	Overrides the options set at the role level.
dqi	The data quality impact value.	float	N/A
description	A string that describes the end node, as seen from the other end.	string	Overrides the description set at the role level. Can contain format strings.
translations	An object that maps a locale to a translated label for the end node.	object	Overrides the translation set at the role level. Can contain format strings.