Configuring dependency visualizations
The Dependency Visualization links displayed in the Visualization list in the user interface (UI) are generated from a visualization configuration file. For more information, see the Viewing dependency visualizations section. You can now add new visualizations to this configuration file, edit existing ones or remove them from the visualization list.
- Configuration File Location - The default configuration file can be found in the following location:
This default configuration file must not be changed.
- Configuration File Customisation - To customize a configuration file, create the following:
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. For an explanation of each of these, see the following sections:
The visualization definition section contains a number of definitions for visualizations. Each definition takes the form:
visualization_name– the name of the visualization. This is displayed in the visualizations list when viewing a node of the type defined in
tab_name– the tab under which to display the visualization. Valid values are:
- If no tab is specified, no tab is selected when the visualization is displayed.
viewed_node_type– the type of node for which this visualization is available.
type_of_dependency- the type of dependency, for example,
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
This defines a visualization called
Dependency which will be available on the visualizations list when viewing a
SoftwareInstance or a
BusinessApplicationInstance. When displayed, the Infrastructure tab will be selected.
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
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.
The dependency definition (
type_of_dependency) defines the route from the
viewed_node_type to the
For example, the following visualization definition, from the first section of the file, shows all Hosts that a SoftwareInstance is running on:
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:
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:
The visualization will show only Host and Subnet nodes, but in order to get to Subnet nodes from Host nodes, it will traverse through NetworkInterface nodes.
You can also define a number of alternative paths by listing them on separate lines:
Each path will be tried in turn, and all resulting nodes connected to the source node will be returned.
Relationships can be wildcarded in the same way as in a generic search using
Traversal steps can have an optional '+' after them, for example:
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 can be set on a dependency definition that affect how it is rendered. For example:
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: 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.
- traverse to the destination nodes using the given traversal
- represent the source node as a box
- add the destination nodes in the 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.
right_box attributes override 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.
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:
define it like this:
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:
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.
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: