Topology Visualization

Graph and Map components allow to visualize device topology, i.e. links between devices.

Topology visualization is configured by a number of properties:

Selects topology data provider type. The list of available types may vary in different Iotellect installations. For example, available types may include:

• Custom (Visualizes any device-to-device links that are defined in a non-standard way)

• Network (Network topology of all types, i.e. both Level 2 and Level 3)

• Level 2 (OSI model layer 2 topology)

• Level 3 (OSI model layer 3 topology)

For a Map component, the Provider can be set to an empty string to disable topology visualization.

Property name: provider

Property type: String

Defines whether each source and target mode is a context. If this flag is enabled, different expressions that evaluate node properties may refer to this context as a default context. If this flag is unchecked, Source Expression and Target Expression return node names instead of their context paths.

Property name: contextMode

Property type: Boolean

Defines if nodes that don't have any links are shown.

Property name: displayUnlinkedNodes

Property type: Boolean

Used only by the Custom topology provider. This expression must result to a Data Table. This Data Table becomes the default data table for Node Expression and Link Expression.

Property name: topologyExpression

Property type: String

Used only by the Custom topology provider. This expression must result to a Data Table. Each record in this table will define one topology link. For each link, you need to specify the identifier of the link, the source node, and the target node. This data is then retrieved by Link Id Expression, Source Expression and Target Expression. The record may also define other link properties, such as color, width, and description. Those properties will be retrieved via Color Expression, Width Expression, etc.

Property name: linkExpression

Property type: String

Used only by the Custom topology provider. This expression is evaluated for every record of a table returned by Link Expression. The expression must result to a String that will be interpreted as an Id of a link.

Property name: linkIdExpression

Property type: String

Used only by the Custom topology provider. This expression is evaluated for every record of a table returned by Topology Expression. The expression must result to a String that will be interpreted as a path of a topology link source context (e.g. device context).

Property name: sourceExpression

Property type: String

Used only by Custom topology provider. This expression is evaluated for every record of a table returned by Topology Expression. The expression must result to a String that will be interpreted as a path of topology link target context (e.g. device context).

Property name: targetExpression

Property type: String

Used only by the Custom topology provider. This expression must result to a Data Table. Each record in this table defines one topology node, so it must contain information for Link Id Expression. The record may also define other node properties, such as color, width, description, etc. These other node properties can be accessed by other expressions such as Color Expression or Type Expression.

Property name: nodeExpression

Property type: String

Used only by the Custom topology provider. This expression is evaluated for every record of a table returned by Node Expression. The expression must result to a String that will be interpreted as an Id of node.

Property name: nodeIdExpression

Property type: String

An expression that is evaluated to an action name. This expression runs upon a click on an event's source context. If empty (not specified), context's default action will be launched.

Property name: preferredActionNameExpression

Property type: String

For example, this expression {info$type} == "group.device" ? "dashboard_admin_SwitchDashboard" : "manage" opens the provided dashboard SwitchDashboard for a device group and the default dashboard for a device.

Configuration of dynamic labels indicating the current device state.

Properties of a label:

Property name: nodeDescriptionExpression

Property type: Data Table

This expression is evaluated for every Context that is a source or a target of any topology link. Is should result to a Color that will be used to render the topology node.

Property name: colorExpression

Property type: String

This expression is evaluated for every Context that is a source or a target of any topology link. It should result to a String that will be treated as a topology node icon file name.

Topology node icons are located in /images/shapes subfolder of the Iotellect installation folder. Icon file name must match a String returned by the Type Expression. Icon file extension must be .svg, i.e. all icons are SVG vector images.

Each SVG image used as a topology node icon must include just a single element (tag) inside its <svg></svg> tag. This tag can be, for example, a <path>, a <circle>, or any other allowed SVG element. No nesting is allowed.

Property name: typeExpression

Property type: String

This optional expression is evaluated for every Context that is a source or a target of any topology link. It should result to an Integer number that indicates an interface of a source/target node that the current link belongs to.

Property name: interfaceExpression

Property type: String

This optional expression is evaluated for every topology link. It should result to a Boolean value that defines whether the link is directed (i.e. heading from its Source to Target) or undirected. All links are undirected by default.

This property is not available for Tree, Radial or Balloon layouts. These layouts are not recommended for topology visualization because the initial information about the link direction is overridden by the layout algorithm.

Property name: directedExpression

Property type: String

This optional expression is evaluated for every topology link. It should result to a floating point number defining topology link width. The default link width is 1 pixel.

Property name: widthExpression

Property type: String

This optional expression is evaluated for every topology link. It should result to a String that will define custom description of a topology link.

Property name: linkDescriptionExpression

Property type: String

If this flag is enabled, the link description will be shown.

Property name: linkDescriptionShowMode

Property type: Boolean

This optional expression is evaluated for every topology link. It should result to a Color that will be used to render the topology link.

If the color expression is empty or return empty value, link will take the gradient color from the source and target nodes.

Property name: linkColorExpression

Property type: String

Expression which returns image of the layer objects.

Property name: imageExpression

Property type: String

Default expression (select({users.admin.models.deviceImages:deviceImages}, 'image', 'name', {.:genericProperties$type})) takes images from Device Images

Disables possibility to delete or save layouts.

This optional expression is evaluated for every topology node. It should result to a String that will define the tooltip for a topology node.

Property name: nodeTooltipExpression

Property type: String

This optional expression is evaluated for every topology link (edge). It should result to a String that will define a tooltip for a topology link.

Property name: linkTooltipExpression

Property type: String

You can right-click a node to open the node actions menu. A click on an option in this menu generates an event with the defined name.

Property name: vertexPopupMenu

Property type: Data Table

You can right-click an edge (link) to open the edge actions menu. A click on an option in this menu generates an event with the defined name.

Property name: edgePopupMenu

Property type: Data Table

Enables the display of neighbouring nodes. For each node, all nodes that belong to the same path will be displayed in the topology.

Enabling this property can seriously reduce the performance.

Property name: showNeighbouringNodes

Property type: Boolean

Expression which returns rotation ratio of the layer objects.

Property name: azimuthExpression

Property type: String

Expression which returns size ratio of the layer objects.

Property name: ratioExpression

Property type: String

This example explains how to use Custom topology provider to visualize device parent-to-child relationship defined by Device Connectivity model included into Iotellect Network Manager product.

The Device Connectivity model attaches a tabular Parents property to every Network Host device (can be easily attached to all devices). The Parents table has Path field representing context path of parent devices. The table contains a list of devices that affect network connectivity of a current device.

To visualize all child-to-parent links on a topology graph or map, we'll need the following setup of the Custom topology provider:

• Topology Expression: callFunction("", "executeQuery", "SELECT parents.parents$path as parent, children.info$remotePath as child FROM users.*.devices.*:parents as parents LEFT OUTER JOIN users.*.devices.*:info as children ON children$CONTEXT_ID = parents$CONTEXT_ID"). This expression executes a query that returns a list of all device-to-parent links defined in Iotellect Server and accessible by the current user. Query result table has parent and child fields containing paths of link endpoint contexts.

• Source Expression: {parent}. This expression retrieves link source context path from each row of the above query's results.

• Target Expression: {child}. This expression retrieves link target context path from each row of the above query's results.

• All other expressions may be left at their defaults as they will extract data from link source and target contexts.

This example explains how Custom topology expressions are interconnected and how to build topologies using these expressions.

For the sake of simplicity, this example uses two data tables as a source of all data about the topology. If you want to apply this example to scenarios, replace Node Expression and Link Expression with expressions that return relevant data in a similar format.

The root expression for the Custom topology is Topology Expression. The data table returned by this expression holds all data for the topology. Two other expressions, Node Expression and Link Expression, use this table as the default data table. Node Expression uses it to retrieve information about nodes. Link Expression uses it to retrieve information about connections between nodes. Because it is much simpler to use two different data tables for links and for nodes, you can leave Topology Expression empty and specify Node Expression and Link Expression independently. Data tables returned by Node Expression and Link Expression will be used by all other expressions.

Data table returned by Link Expression is the source of information about links. Because Custom topology is flexible, it is up to you to define a way that the data will be stored and retrieved from this data table by other expressions for links. The bare minimum required for the topology is Link Id Expression, Source Expression, and Target Expression. If you define these three properties, topology will be built from this data alone. Iotellect will get node data from Source Expression and Target Expression and build links between these nodes. All expressions that use the data table returned by Link Expression: Link Id Expression, Source Expression, Target Expression, Interface Expression, Directed Expression, Width Expression, Link Description, Link Color Expression.

Data table returned by Node Expression is the source of information about nodes. Again, it is up to you to define how much data about the nodes you want to be stored and displayed. All expressions that use the data table returned by Node Expression: Node Id Expression, Type  Expression, Node Description Expression, Color Expression.

In this example, you'll be creating two data tables.

The first table will store information about links. This is the only table required to build a topology.

The linkData table has the following fields:

The second table will store information about nodes. This table is used to display the nodes on the graph. To keep things simple, only node name, color, and description are used.

The nodeData table has the following fields:

These two tables are enough to build a custom topology. Use the following expressions to do so:

Topology Expression. This is the parent expression for all topology. Because it is not used in this example, leave it empty.

Node Expression. This expression must result in a data table described above. For example, you can execute a query that returns all the data for your topology. This example uses a reference to a variable that stores the node data table: {users.admin.models.customTopology:nodeData}. This data table becomes the default data table for all other expressions related to nodes.

Link Expression. This expression must result in a data table described above. This example uses a reference to a variable that stores the link data table: {users.admin.models.customTopology:linkData}. This data table becomes the default data table for all other expressions related to links.

Link Id Expression. This expression must result in a link identifier. Each link identifier corresponds to a single link between two nodes. This example uses the linkId field of the link data table: {linkId}.

Source Expression. Each link must have a source node where it originates. This expression defines how this source node is determined. This example uses the sourceNode field of the link data table that holds node identifiers: {sourceNode}.

Target Expression. This expression defines how to determine a target node for a link. This example uses the targetNode field of the link data table that holds node identifiers: {targetNode}.

Directed Expression. This expression defines whether the link must be displayed as directed. This example uses the isDirected field for this: {isDirected}

Width Expression. This expression defines the displayed link width. This example uses the linkWidth field for this: {linkWidth}.

Link Color Expression. This expression defines the displayed link color. This example uses the linkColor field for this: {linkColor}.

Link Description. This expression defines the label displayed for the link. This example uses the linkDescription field for this: {linkDescription}.

Node Id Expression. This expression must result in a node identifier. Each node identifier corresponds to a single node. Node identifiers must match the identifiers used in the data table for links. This example uses the nodeName field for this: {nodeName}.

Color Expression. This expression defines the displayed node color. This example uses the nodeColor field for this: {nodeColor}.

Node Description Expression. This property is a data table that defines the placement of the labels for nodes. This example uses the nodeDescription as the Expression field value: {nodeDescription}. All other fields define the visual properties of the label.

Example node data set for custom topology:

Example link data set for custom topology:

Was this page helpful?

Tell us more

Send

Thank you!