The Dependency Visualization links displayed in the Visualization drop-down dialog in the UI are generated from a visualization configuration file. See Viewing Dependency Visualizations section for more information. You can now add new visualizations to this configuration file, edit existing ones or remove them from the visualization drop-down.

Notes:

1. Configuration File Location - The default configuration file can be found in the following location:
   /usr/tideway/data/default/graph-definition.txt
   This default configuration file must not be changed.
2. Configuration File Customisation - To customize a configuration file, create the following:
   /usr/tideway/data/customer/graph-definition.txt
   This overlays the default configuration file.

Structure of the file

The file is divided into three sections by rows of equals signs. The first section defines Visualization Definitions, the second Dependency Definitions, and the third Tooltip Definitions. See the sections below for an explanation of each of these.

Visualization Definitions

The visualization definition section contains a number of definitions for visualizations. Each definition takes the form:

visualization_name
  viewed_node_type
    type_of_dependency dependency_target_node_type
    type_of_dependency dependency_target_node_type
    ...
    type_of_dependency dependency_target_node_type

• visualization_name – the name of the visualization. This is displayed in the visualizations drop-down when viewing a node of the type defined in viewed_node_type.
• viewed_node_type – the type of node for which this visualization is available.
• type_of_dependency - the type of dependency, for example, depended_upon, or dependant.
• dependency_target_node_type - the node type that is the target for the dependency. For example, in a dependency visualization describing the relationship between a business application running on a host and the host itself, the target is Host.
  For example:

Dependency
  SoftwareInstance
    depended_upon SoftwareInstance
    dependant SoftwareInstance
    running_on Host

  BusinessApplicationInstance
    depended_upon BusinessApplicationInstance
    dependant BusinessApplicationInstance
    running_on Host

This defines a visualization called Dependency which will be available on the visualizations drop-down when viewing a SoftwareInstance or a BusinessApplicationInstance.

When you pick the SoftwareInstance visualisation, you see the SoftwareInstance node as the starting point of the visualisation, and then all SoftwareInstance and Host nodes related to that SoftwareInstance. Exactly which SoftwareInstance and Host nodes are shown depends on the definition of the depended_upon, dependant, and running_on dependency definitions, which are defined in the dependency definitions part of this file.

The indentation is important and defines the structure of the visualization. An indentation must be composed of spaces, not tabs, and be a multiple of two spaces.

Dependency Definitions

The dependency definition (type_of_dependency) defines the route from the viewed_node_type to the dependency_target_node_type.
For example, the following visualization definition, from the first section of the file, shows all Hosts that a SoftwareInstance is running on:

Dependency
  SoftwareInstance
    running_on Host

The running_on Host relationship defines the route from the SoftwareInstance to the Host. One of these definitions must exist in the dependency definitions For example:

SoftwareInstance
  running_on Host
    RunningSoftware:HostedSoftware:Host:Host

Here, SoftwareInstance is defined as the source node kind and Host is defined as the destination node kind, and the system will use the traversal RunningSoftware:HostedSoftware:Host:Host to get from any SoftwareInstance nodes currently in the visualization to any related Host nodes.

A dependency definition can have multiple traversals chained one after the other in order to get to a node kind that is distantly related:

Host
  connected_to Subnet
    DeviceWithInterface:DeviceInterface:InterfaceOfDevice:NetworkInterface DeviceOnSubnet:DeviceSubnet:Subnet:Subnet

The visualization will show only Host and Subnet nodes, but in order to get to Subnet nodes from Host nodes, it will traverse via NetworkInterface nodes.

You can also define a number of alternative paths by listing them on separate lines:

SoftwareInstance 
  communication SoftwareInstance
    Server:Communication:Client:SoftwareInstance
    Client:Communication:Server:SoftwareInstance

Each path will be tried in turn, and all resulting nodes connected to the source node.

Relationships can be wildcarded in the usual way:

 SoftwareInstance
  composed_of DiscoveredProcess
    InferredElement:Inference::DiscoveredProcess

Traversal steps can have an optional '+' after them, for example:

SoftwareContainer:SoftwareContainment:ContainedSoftware:SoftwareInstance+

This causes the step to be followed repeatedly, adding nodes to the set of nodes found so far, until further traversals add no further nodes. The step is always evaluated at least once. A good use of this function is to follow a relationship that forms an arbitrarily deep hierarchy: for example, the SoftwareInstances making up a BAI. Here it is possible to have a first-order SoftwareInstance with a second-order SoftwareInstance as the container, before reaching the BAI. Although not recommended and not often seen, a third-order SoftwareInstance can be inserted between the second order SoftwareInstance and the BAI, and so on. This function will navigate this structure.

Attributes

Attributes can be set on a dependency definition that affect how it is rendered. For example:

SoftwareInstance
  communication.server SoftwareInstance (color=0f0,left_arrow)
      Server:Communication:Client:SoftwareInstance
  communication.client SoftwareInstance (color=0f0,right_arrow)
      Client:Communication:Server:SoftwareInstance

This displays lines between SoftwareInstance nodes representing client/server communications in green, and draws an arrow pointing at the server.

Attributes appear in brackets after the definition of the dependency type and destination node kind. No spaces are allowed between the brackets, and the attributes are a comma separated list of either flags, or key and value.

Defined attributes are:

   color=rgb
   left_arrow
   right_arrow
   left_box
   right_box

• color – sets the color of the line in the graph. It takes a three character argument that is the color as an RGB tuple. Each character is the color of that component as a hexadecimal digit (0-f).
• left_arrow - sets arrow heads on the line, pointing to the source node.
• right_arrow - sets arrow heads on the line, pointing to the target node.
  Both attributes can be set, in which case both ends of the line have an arrow, and neither attribute can be set, in which case the line is plain.
• left_box
  • traverse to the destination nodes using the given traversal
  • represent the source node as a box
  • add the destination nodes in the box
• right_box
  • traverse to the destination node using the given traversal
  • represent the destination node as a box
  • add the source node in that box

Note that there must only be a single destination node when using right_box, because it is impossible to turn several destination nodes into separate boxes and put the source node inside each of them. It should be used when it is known there will always be at most one destination node, for example the HostContainer for a Host.

Boxes only appear at the top level; they cannot be nested. If a later definition conflicts with an earlier, for example attempting to nest boxes or put a node inside two different boxes, the later definition overrides the earlier. The order depends on how the graph is constructed and is not predictable.

The left_box and right_box attributes override the color, left_arrow, and right_arrow attributes.

Special traversals

The :NetworkConnections:: traversal which can be used with Hosts and DiscoveredProcesses, connects nodes based on observed communication information. Observed communication information is directly discovered, rather than specific communication relationships built by patterns.

DiscoveredNetworkConnections and ListeningPorts are used to find this information. These types of traversal are quite slow.

Notes for defining traversals

It is recommended that arrows on edges point towards the depended upon node. For example the Switch on an edge between Host and Switch, or the SoftwareInstance on an edge between BAI and SoftwareInstance. This will ensure the layout algorithm lays the graph out properly when in hierarchical layout mode.

It makes sense to name traversals as a verb phrase that can be read in the middle of the start and end node kinds (where end is defined as the node with the arrow head and start is the other one). For example SoftwareInstance running_on Host. This makes it easy to read off what any given edge in the visualization means.

It is also recommended that when defining a pair of traversals for moving between nodes in either direction (eg. from Host to SoftwareInstance and from SoftwareInstance to Host, both using the "RunningSoftware" relationship), that the traversal is named the same thing. In other words, instead of defining the two traverals like this:

  Host
    has_running_on_it SoftwareInstance (right_arrow)
      Host:HostedSoftware:RunningSoftware:SoftwareInstance
  SoftwareInstance
    is_running_on Host (right_arrow)
      RunningSoftware:HostedSoftware:Host:Host

define it like this:

  Host
    running_on SoftwareInstance (left_arrow)
      Host:HostedSoftware:RunningSoftware:SoftwareInstance
  SoftwareInstance
    running_on Host (right_arrow)
      RunningSoftware:HostedSoftware:Host:Host

The latter form ensures that the edges all point towards the depended upon node (the Host), and also keeps the name the same. If the name, attributes (color and dashed), and source and destination nodes are the same, but the arrow and source and destination nodes are opposites, the two edges will be merged. Without this, the visualization can become ugly as lots of edges will be double edges.

There is one case where a pair of opposite traversals cannot have the same name: when the source and destination nodes are the same node kind. For example:

  SoftwareInstance
    depended_upon SoftwareInstance (color=00f,right_arrow)
      Dependant:Dependency:DependedUpon:SoftwareInstance
    dependant SoftwareInstance (color=00f,right_arrow)
      DependedUpon:Dependency:Dependant:SoftwareInstance

Ideally the traversals should be called the same thing, as they are opposites of each other. But because the source and destination nodes are the same, there is no way to distinguish them other than to use a different traversal name. In this case, the visualization might end up with two edges between a pair of SoftwareInstances, one pointing one way and labelled "depended_upon" and the other pointing the other way and labelled "dependant".

It is a convention to use the name "xxxxx.box" for "box" traversals, ie. those that put the source or destination nodes in a box by using left_box or right_box. This is because often the non-box case is also required in some visualizations. With this naming scheme, it is clear which form is being used.

Tooltip Definitions

By default, the attributes shown as a tooltip when a user hovers over a node are read from the summary list defined in the taxonomy. The tooltip section allows that to be overridden. For example:

Host
  name
  os_class