Skip to main content

Graph Topology

The Graph Topology Moobot module allows you to create, manage and query multiple named topologies, and their nodes and links.

If your topology .csv file is larger than 40 MB Moogsoft recommends using the Topology Loader utility. See Load a Topology for information on the loader utility.

Load the module

The Graph Topology module is available to load into any standard Moobot. To load it, define a new global variable at the top of the Moobot Javascript file. For example:

var graphtopo = MooBot.loadModule('GraphTopo');

Method reference

The Graph Topology module uses the following methods.

createTopologies

Creates one or more topologies.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topologies

Array of JSON objects

Yes

One or more topology objects containing topology properties.

Topology properties

The topology objects can contain the following properties:

Name

Type

Required

Description

name

String

Yes

Name of the topology. Must be less than 256 characters.

active

Boolean

No

Flag to set the topology to active (true) or inactive (false). Default is false.

description

String

No

Description of the topology. Must be less than 1001 characters.

Response

The method returns the following response.

Type

Description

Array of JSON objects

One or more objects containing the details of any topologies that could not be created.

Example

Example function using the createTopologies method to create two topologies named "host" and "location":

function createTopologies()
{
    logger.warning("Creating topologies");
    var topo1 = 
    {
         name: "host",
         description: "Host-based topology",
         active: true
    }; 
    var topo2 = 
    {
         name: "location",
         description: "Location-based topology",
         active: true
    };
    var topologiesNotCreated = graphtopo.createTopologies([topo1, topo2]);  
    logger.warning("Returned object to string from createTopologies: " + JSON.stringify(topologiesNotCreated));
}

updateTopologies

Updates one or more topologies.

You can also use this function to create a topology. If name does not exist the endpoint creates it.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topologies

Array of JSON objects

Yes

One or more topology objects containing topology properties.

Topology properties

The topology objects can contain the following properties:

Name

Type

Required

Description

name

String

Yes

Name of the topology. Must be less than 256 characters. You cannot update the topology name. To rename a topology use the replaceTopology method.

active

Boolean

No

Flag to set the topology to active (true) or inactive (false).

description

String

No

Description of the topology. Must be less than 1001 characters.

Response

The method returns the following response.

Type

Description

Array of JSON objects

One or more objects containing the details of any topologies that could not be updated.

The request fails if any of the following are true:

  • The topology you're trying to update does not exist.

  • The topology you're trying to update is being used to filter a Recipe and you are trying to make it inactive.

Example

Example function using the updateTopologies method to update the descriptions of two topologies named "host" and "location":

function updateTopologies()
{
    logger.warning("Updating topologies");
    var topo1 = 
    {
        name: "host",
        description: "Host-based network topology"
    }; 
    var topo2 = 
    {
        name: "location",
        description: "Location-based network topology"
    };
    var topologiesNotUpdated = graphtopo.updateTopologies([topo1, topo2]);  
    logger.warning("Returned object to string from updateTopologies: " + JSON.stringify(topologiesNotUpdated));
}

deleteTopology

Deletes a single topology. Note the following:

  • You cannot delete a topology if it's being used to filter a Recipe.

  • Deleting a topology will impact your ability to restore associated Recipes in future. In order to restore a Recipe that filters on a named topology, the topology must still exist in Moogsoft Onprem.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

name

String

Yes

Name of the topology.

Response

The method returns the following response.

Type

Description

Boolean

true: Topology was deleted.

false: Topology was not deleted.

The request fails if name is being used to filter a Recipe, or does not exist.

Example

Example function using the deleteTopology method to delete a topology named "host":

function deleteTopo(host) 
{    
    var deleteTopoResult = graphtopo.deleteTopology(host);    
    logger.warning("Returned object to string from deleteTopo: " + JSON.stringify(deleteTopoResult));
}

getTopology

Retrieves a single topology.

You can also use this function to determine whether a topology exists. If getTopology returns null, the specified topology does not exist.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

name

String

Yes

Name of the topology.

Response

The method returns the following response.

Type

Description

JSON object

Object containing the topology details.

Example

Example request using the getTopology method to retrieve a topology named "host":

var topology = graphtopo.getTopology(host);

The response object contains details of the "host" topology:

{
    name: "host", 
    description: "Host-based topology",
    active: true
}

getActiveTopologies

Retrieves all active topologies.

Request arguments

The method takes no request arguments.

Response

The method returns the following response.

Type

Description

Array of JSON objects

One or more objects containing the details of active topologies.

Example

Example request using the getActiveTopologies method to retrieve all active topologies:

var active = graphtopo.getActiveTopologies();

The response object contains details of all active topologies:

[
    {
        name: "host", 
        description: "Host-based topology",
        active: true
    },
    {
        name: "location", 
        description: "Location-based topology",
        active: true
    }
]

getInactiveTopologies

Retrieves all inactive topologies.

Request arguments

The method takes no request arguments.

Response

The method returns the following response.

Type

Description

JSON object

Object containing the details of all inactive topologies.

Example

Example request using the getInactiveTopologies method to retrieve all inactive topologies:

var inactive = graphtopo.getInactiveTopologies();

The response object contains details of all inactive topologies:

[
    {
        name: "virtual", 
        description: "Virtual topology",
        active: false
    },
    {
        name: "physical", 
        description: "Physical topology",
        active: false
    }
]

getTopologiesForSituation

Retrieves all topologies linked to a specified Situation.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

sitn_id

Number

Yes

ID of the Situation for which to retrieve topologies.

Response

The method returns the following response.

Type

Description

Array of JSON objects

One or more objects containing the details of topologies linked to the Situation, including topology name and a flag indicating whether this topology caused the Situation to be created.

Example

Example request using the getTopologiesForSituation method to retrieve all topologies linked to Situation 12:

var situationtopos = graphtopo.getTopologiesForSituation(12);

The response object contains details of all linked topologies and their causal flags:

[
    {
        "name" : "host", 
        "causal" : true 
    }, 
    { 
        "name" : "location", 
        "causal" : false 
    }
]

cloneTopology

Clones an existing topology and sets the clone to inactive.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topoName

String

Yes

Name of the topology to clone.

cloneTopoName

String

Yes

Name for the cloned topology. Must be less than 256 characters.

Response

The method returns the following response.

Type

Description

JSON object

Object containing details of the cloned topology.

Example

Example function using the cloneTopology method to clone the "host" topology and name the clone "host_new":

function cloneTopology(host, host_new) 
{  
    logger.warning("Calling function cloneTopology for topo: [" + host + "] - new name will be: [" + host_new + "]");  
    var clonedTopology = graphtopo.cloneTopology(host, host_new);
    logger.warning("Returned object to string from cloneTopology: " + JSON.stringify(clonedTopology));
}

The response contains details of the "host_new" topology:

{ 
    "name" : "host_new", 
    "description" : "host-based topology",
    "active": false
}

replaceTopology

Replaces an existing topology with another topology. This process deletes the original topology. You can use the clone and replace Graph Topology methods to update a copy of an existing topology and then replace a topology with the updated version.

You can also use this method to rename a topology.

When a topology is replaced:

  • The original topology and its nodes and links are deleted.

  • Alerts that reference the original topology are updated to reference the replacement topology.

  • If the replacement topology is active, its processing state in the database is set to outdated. This triggers the graph analyser process to run as part of the Housekeeper Moolet to calculate Vertex Entropy for the topology nodes. See Topology Overview for more information.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topoName

String

Yes

Replace: The name of the existing topology to replace.

Rename: The new topology name.

topology

JSON object

Yes

Object containing properties of the replacing topology, or the topology to rename.

Topology properties

The topology object contains the following properties:

Name

Type

Required

Description

name

String

Yes

Replace: Name of the replacing topology.

Rename: The topology to rename.

active

Boolean

No

Sets the replaced or renamed topology to active (true) or inactive (false). Replaced topologies take the active status of the replacing topology by default.

Response

The method returns the following response.

Type

Description

JSON object

Object containing details of the newly replaced or renamed topology.

The request fails if any of the following are true:

  • name is being used to filter a Recipe, or does not exist.

  • topoName is being used to filter a Recipe and you are trying to make it inactive.

Example

Example function using the replaceTopology method to replace the "host" topology with the "host_new" topology and set its status to active:

function replaceTopology(host, host_new) 
{  
    logger.warning("Calling function replaceTopology - topology to replace: [" + host + "], replacing topology: [" + host_new + "]");  
    var replacingTopology = { name: host_new, active: true };
    var replacedTopology = graphtopo.replaceTopology(host, replacing_topology);  
    logger.warning("Returned object to string from replaceTopology: " + JSON.stringify(replacedTopology));
}

In this example, if there is no topology named "host" the "host_new" topology is renamed "host".

createNodes

Creates nodes in a specified topology.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topoName

String

Yes

Name of the topology in which to create the nodes.

nodes

Array of JSON objects

Yes

One or more node objects containing node properties.

Node properties

The node objects can contain the following properties:

Name

Type

Required

Description

name

String

Yes

Name of the node. Must be less than 256 characters.

description

String

No

Description of the node. Must be less than 1001 characters.

Response

The method returns the following response.

Type

Description

Array of JSON objects

One or more objects containing the details of any nodes that could not be created.

Example

Example function using the createNodes method to create two nodes in the "host" topology named "node1" and "node2":

function createNodes()
{
    logger.warning("Creating nodes");
    var node1 = 
    {
        name: "node1",
        description: "First node"
    }; 
    var node2 = 
    {
        name: "node2",
        description: "Second node"
    };
    var nodesNotCreated = graphtopo.createNodes(host, [node1, node2]);  
    logger.warning("Returned object to string from createNodes: " + JSON.stringify(nodesNotCreated));
}

updateNodes

Updates specified nodes in a specified topology.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topoName

String

Yes

Name of the topology in which to create the nodes.

nodes

Array of JSON objects

Yes

One or more node objects containing node properties.

Node properties

The nodes objects can contain the following properties:

Name

Type

Required

Description

name

String

Yes

Name of the node. You cannot update the node name. To rename a node delete it and recreate it with a new name.

description

String

No

Description of the node. Must be less than 1001 characters.

Response

The method returns the following response.

Type

Description

Array of JSON objects

One or more objects containing the details of any nodes that could not be updated.

Example

Example function using the updateNodes method to update two nodes in the "host" topology named "node1" and "node2":

function updateNodes()
{
    logger.warning("Updating nodes");
    var node1 = 
    {
        name: "node1",
        description: "Primary node"
    }; 
    var node2 = 
    {
        name: "node2",
        description: "Secondary node"
    };
    var nodesNotUpdated = graphtopo.updateNodes(host, [node1, node2]);
    logger.warning("Returned object to string from updateNodes: " + JSON.stringify(nodesNotUpdated));
}

deleteNodes

Deletes specified nodes in a specified topology.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topoName

String

Yes

Name of the topology that contains the nodes to delete.

nodes

Array of Strings

Yes

Names of one or more nodes to delete.

Response

The method returns the following response.

Type

Description

Array of Strings

Names of one or more nodes that could not be deleted.

Example

Example function using the deleteNodes method to delete two nodes in the "host" topology named "node1" and "node2":

function deleteNodes()
{
    logger.warning("Deleting nodes");
    var nodesNotDeleted = graphtopo.deleteNodes(host, ["node1", "node2"]);  
    logger.warning("Returned object to string from deleteNodes: " + JSON.stringify(nodesNotDeleted));
}

getNode

Retrieves details of a single node in a specified topology.

You can also use this function to determine whether a node exists. If getNode returns null, the specified node does not exist.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topoName

String

Yes

Name of the topology containing the node.

nodeName

String

Yes

Name of the node.

Response

The method returns the following response.

Type

Description

JSON object

Object containing the node details.

Example

Example using the getNode method to return details of "node1" in the "host" topology.

var node1 = graphtopo.getNode("host", "node1");

The response object contains the node details:

{
    name: "node1", 
    description: "First node"
}

getAllNodes

Retrieves details of all nodes in a specified topology.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topoName

String

Yes

Name of the topology containing the nodes.

Response

The method returns the following response.

Type

Description

JSON object

Object containing details of the nodes.

Example

Example using the getAllNodes method to return details of all nodes in the "host" topology:

var allNodes = graphtopo.getAllNodes("host");

The response object contains details of the nodes in the "host" topology:

[
    {
        name: "node1", 
        description: First node
    },
    {
        name: "node2", 
        description: Second node
    }
]

isConnected

Checks whether a specified node is part of a topology.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topoName

String

Yes

Name of the topology that contains the node.

nodeName

String

Yes

Name of the node.

Response

The method returns the following response.

Type

Description

Boolean

true: Node in topology.

false: Node not in topology.

Example

Example using the isConnected method to check whether the "node1" node is in the "host" topology.

var isNodeInTopo = graphtopo.isConnected("host", "node1");

numberOfConnections

Counts the number of links from a specified node in a specified topology.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topoName

String

Yes

Name of the topology that contains the node.

nodeName

String

Yes

Name of the node for which to count the links.

Response

The method returns the following response.

Type

Description

Number

The number of connections from the node. Returns 0 if the node does not exist or has no connections, or the topology does not exist.

Example

Example using the numberOfConnections method to return the number of connections from node "node1" in the "host" topology:

var return = topo.numberOfConnections("host", "node1");
logger.warning("numberOfConnections -> " + return);

This example logs the following message:

WARN : ... [CLogModule.java]:99 +|numberOfConnections -> 3|+

distance(topoName, sourceNode, sinkNode)

Calculates the number of hops between two specified nodes in a specified topology.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topoName

String

Yes

Name of the topology that contains the nodes.

sourceNode

String

Yes

Name of the source node. Must be less than 256 characters. Note that topology links in Moogsoft Onprem are bidirectional. If the node does not exist, the endpoint will create it.

sinkNode

String

Yes

Name of the sink node. Must be less than 256 characters. Note that topology links in Moogsoft Onprem are bidirectional. If the node does not exist, the endpoint will create it.

Response

The method returns the following response.

Type

Description

Double

The number of hops between the nodes. Returns -1 if the nodes are not connected.

Example

Example function using the distance method to calculate the number of hops between nodes "node1" and "node2" in the "host" topology:

function distance(host, node1, node2) 
{
    logger.warning("Calling function distance for topo: [" + host + "] and nodes: [" + node1 + "], [" + node2 + "]");
    var distance = graphtopo.distance(host, nost1, node2);
    logger.warning("Returned object to string from distance: " + JSON.stringify(distance));
}

distance(topoName, sourceNode, sinkNode, radius)

Calculates the number of hops between two specified nodes in a specified topology, up to a maximum number of hops.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topoName

String

Yes

Name of the topology that contains the nodes.

sourceNode

String

Yes

Name of the source node. Note that topology links in Moogsoft Onprem are bidirectional.

sinkNode

String

Yes

Name of the sink node. Note that topology links in Moogsoft Onprem are bidirectional.

radius

Double

Yes

Maximum number of hops to count.

Response

The method returns the following response.

Type

Description

Double

The number of hops between the nodes. Returns -1 if the nodes are not connected or the number of hops is larger than the radius.

Example

Example function using the distance method to calculate the distance between nodes "node1" and "node2" in the "host" topology, where the number of hops is 5 or less:

function distance(host, node1, node2, 5.0) 
{
    logger.warning("Calling function distance (with max hops) for topo: [" + host + "] and nodes: [" + node1 + "], [" + node2 + "] and radius: [5.0]");
    var distanceWithMaxHops = graphtopo.distance(host, node1, node2, 5.0);
    logger.warning("Returned object to string from distance (with max hops): " + JSON.stringify(distance));
}

getAllLinksForTopology

Retrieves all links for a specified topology.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topoName

String

Yes

Name of the topology containing the links.

Response

The method returns the following response.

Type

Description

Array of JSON objects

One or more objects containing details of the links.

Example

Example using the getAllLinksForTopology method to retrieve details of all links in the "host" topology:

var linkDetails = graphtopo.getAllLinksForTopology("host");

The response object contains details of the links:

[
    {
        description: "link1",
        sourceNode: "node1",
        sinkNode: "node2"
    },
    {
        description: "link2",
        sourceNode: "node2",
        sinkNode: "node3"
    }
]

getAllLinksForNode

Retrieves all links for specified node in a specified topology.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topoName

String

Yes

Name of the topology containing the links.

nodeName

String

Yes

Name of the node.

Response

The method returns the following response.

Type

Description

Array of JSON objects

One or more objects containing details of the links.

Example

Example using the getAllLinksForNode method to retrieve link details for the "node2" node in the "host" topology:

var linksForNode = graphtopo.getAllLinksForNode("host", "node2");

The response object contains details of the links:

[
    {
        description: "link1",
        sourceNode: "node2",
        sinkNode: "node1"
    },
    {
        description: "link2",
        sourceNode: "node2",
        sinkNode: "node3"
    }
]

deleteAllLinksForNode

Deletes all links for a specified node in a specified topology.

Request arguments

The method takes the following arguments.

Name

Type

Required

Description

topoName

String

Yes

Name of the topology containing the links.

nodeName

String

Yes

Name of the node.

Response

The method returns the following response.

Type

Description

Boolean

true: Links were deleted.

false: Links were not deleted.

Example

Example using the deleteAllLinksForNode method to delete all links for the "node2" node in the "host" topology:

var deleteLinks = graphtopo.deleteAllLinksForNode("host", "node2");

Deprecated methods

The following Topology methods are no longer supported.

loadTopology

Use getTopology.

isConnected(node)

Use getNode.

connected(node1, node2)

Use isConnected.

numberOfConnections(node)

Use numberOfConnections.

addEdge(node1, node2)

Use createLinks.

addEdge(node1, node2, weight)

Use createLinks.

distance(node1, node2)

Use distance(topoName, sourceNode, sinkNode).

distance(node1, node2, radius)

Use distance(topoNode, sourceNode, sinkNode, radius).

radialDelta(node1, node2)

Use distance(topoName, sourceNode, sinkNode).