Graph

The Graph library implements the functions for Graph rules.

Synopsis

use Assure1::Graph;

Functions

The Graph library contains the functions described below.The Graph library contains the functions described below.

CloneVertexID

A convenience function that clones a vertex or an entire linked vertex tree. Returns a vertex hash of the new created vertices which contain references to their directional children and depths.

CloneVertexID(\%options)

Options

NDB          -> Neo4j database handle reference, (for example, \$NDB).
VertexID     -> VertexID to clone
CloneTree    -> Indicate whether to clone directionally linked vertices of VertexID as well (0=single, 1=tree)
                NOTE: children vertices cannot be modified during clone, and does not support circular linking
Vertex       -> New Vertex Definition containing Name (required), TimestampModified values, and a Properties hash (optional)

Returns

1. ErrorFlag   (0 Good, 1 Bad)
2. Message     (String)
3. TopVertexID (String)

Synopsis

my ($ErrorFlag, $Message, $TopVertexID) = CloneVertexID({
    NDB         => \$NDB,
    VertexID    => "#10:0",
    Vertex      => {
        Name       => $VertexName,
        Type       => $VertexTypeID
        Properties => {
            Key1 => "Value 1",
            Key2 => "Value 2"
        }
    }
});

if (!$TopVertexID) {
    $Log->Message('ERROR', "Error Cloning Vertex Tree: $Message");
}

OR

my $TopVertexID = CloneVertexID({
    NDB         => \$NDB,
    VertexID    => "#10:0",
    CloneTree   => 1,
    Vertex      => {
        Name       => $VertexName,
        Type       => $VertexTypeID
        Properties => {
            Key1 => "Value 1",
            Key2 => "Value 2"
        }
    }
});

if (!$TopVertexID) {
    $Log->Message('ERROR', "Error Cloning Vertex Tree");
}

CreateEdgeTree

A convenience function that creates an entire edge tree with properties.

CreateEdgeTree(\%options)

Options

NDB          -> Neo4j database handle reference, (for example, \$NDB).
StorageHash  -> Cache (for example, $StorageHash)
EdgeTree     -> Edge Definition and Properties hash (Edge definition can optionally contain VertexType1, VertexType2 and EdgeType)

Returns

1. ErrorFlag  (0 Good, 1 Bad)
2. Message    (String)
3. EdgeID     (String) or undef if error

Synopsis

my ($ErrorFlag, $Message, $EdgeID) = CreateEdgeTree({
    NDB          => \$NDB,
    StorageHash  => $StorageHash,
    EdgeTree     => {
        VertexID1   => $VertexID1,
        VertexID1   => $VertexID2,
        TypeID      => $EdgeTypeID,
        Properties  => {
            Key1  => "Value 1",
            Key2  => "Value 2"
        }
    }
});

if (!$EdgeID) {
    $Log->Message('ERROR', "Error Creating EdgeTree: $Message");
}

OR

my $EdgeID = CreateEdgeTree({
    NDB          => \$NDB,
    StorageHash  => $StorageHash,
    EdgeTree     => {
        VertexID1   => $VertexID1,
        VertexType1 => $VertexType1,
        VertexID2   => $VertexID2,
        VertexType2 => $VertexType2,
        TypeID      => $EdgeTypeID,
        EdgeType    => $EdgeType
        Properties  => {
            Key1  => "Value 1",
            Key2  => "Value 2"
        }
    }
});

if (!$EdgeID) {
    $Log->Message('ERROR', "Error Creating Edge");
}

CreateVertexTree

A convenience function to create an entire vertex tree with properties.

CreateVertexTree(\%options)

Options

DBH         -> Assure1 database handle reference, (for example, \$DBH)
NDB         -> Neo4j database handle reference, (for example, \$NDB).
StorageHash -> Cache (for example, $StorageHash)
VertexTree  -> Vertex Definition and Properties hash

Returns

1. ErrorFlag   (0 Good, 1 Bad)
2. Message     (String)
3. VertexID    (String) or undef if error

Synopsis

my ($ErrorFlag, $Message, $VertexID) = CreateVertexTree({
    DBH         => \$DBH,
    NDB         => \$NDB,
    StorageHash => $StorageHash,
    VertexTree  => {
        Name       => "Vertex 1",
        TypeID     => $VertexTypeID,
        TypeName   => $VertexTypeName,
        Properties => {
            Key1 => "Value 1",
            Key2 => "Value 2"
        }
    }
});

if (!$VertexID) {
    $Log->Message('ERROR', "Error Creating VertexTree: $Message");
}

OR

my $VertexID = CreateVertexTree({
    DBH         => \$DBH,
    NDB         => \$NDB,
    StorageHash => $StorageHash,
    VertexTree  => {
        Name       => "Vertex 1",
        TypeID     => $VertexTypeID,
        Properties => {
            Key1 => "Value 1",
            Key2 => "Value 2"
        }
    }
});

if (!$VertexID) {
    $Log->Message('ERROR', "Error Creating VertexTree");
}

CypherQuote

Determines whether a given value is a number or string, adding necessary quotes or escapes characters where applicable.

CypherQuote(\%options)

Options

value    -> The value to examine

Returns

value    -> The modified value, including any necessary escape characters or quotes.

DeleteEdgeID

Deletes the specified edge.

DeleteEdgeID(\%options)

Options

NDB         -> Neo4j database handle reference, (for example, \$NDB).
StorageHash -> (Recommended) Cache (for example, $StorageHash)
EdgeID      -> Edge to delete
EdgeType    -> (Optional) Edge Type
VertexType1 -> (Optional) Start Vertex Type
VertexType1 -> (Optional) End Vertex Type

Returns

1. ErrorFlag   (0 Good, 1 Bad)
2. Message     (String)

Synopsis

DeleteEdgeID({
    NDB         => \$NDB,
    StorageHash => $StorageHash,
    EdgeID      => $EdgeID
});

DeleteVertexID

Deletes the specified vertex.

DeleteVertexID(\%options)

Options

NDB         -> Neo4j database handle reference, (for example, \$NDB).
StorageHash -> (Recommended) Cache (for example, $StorageHash)
VertexID    -> Vertex to delete
VertexType  -> (Optional) Vertex Type

Returns

1. ErrorFlag   (0 Good, 1 Bad)
2. Message     (String)

Synopsis

DeleteVertexID({
    NDB         => \$NDB,
    StorageHash => $StorageHash,
    VertexID    => $VertexID
});

ExecuteCypherQuery

Runs a Cypher query on a Neo4j database.

ExecuteCypherQuery(\%options)

Options

NDB         -> Neo4j database handle reference, (for example, \$NDB)
CypherQuery -> The Cypher query to run.

Returns

Error        The error message returned from Neo4j, if an error has occurred (undef if query is successful)
Results      The query result, as an array of rows

FindEdgeID

Finds an edge with the specified vertices and type and returns its ID if found. If the Create option is set to true (1), and no edge with the specified name exists, it will be automatically created.

FindEdgeID(\%options)

Options

NDB         -> Neo4j database handle reference, (for example, \$NDB).
StorageHash -> Cache (for example, $StorageHash)
VertexID1   -> Start of Edge
VertexType1 -> (Optional) Vertex Type
VertexID2   -> End of Edge
VertexType2 -> (Optional) Vertex Type
TypeID      -> Edge Type ID
EdgeType    -> (Optional) Edge Type
Create      -> (Optional) Set to 1 to create the collection if it does not exist, set to 0 otherwise.

Returns

1. ErrorFlag (0 Good, 1 Bad)
2. Message   (String)
3. Edge ID   (String) or undef if not found or created.

Synopsis

my ($ErrorFlag, $Message, $EdgeID) = FindEdgeID({
    NDB         => \$NDB,
    StorageHash => $StorageHash,
    VertexID1   => $VertexID1,
    VertexID2   => $VertexID2,
    TypeID      => $EdgeTypeID,
    Create      => 1
});

if (!$EdgeID) {
    $Log->Message('ERROR', "Error Finding Edge: $Message");
}

OR

my $EdgeID = FindEdgeID({
    NDB         => \$NDB,
    StorageHash => $StorageHash,
    VertexID1   => $VertexID1,
    VertexID2   => $VertexID2,
    TypeID      => $EdgeTypeID,
    Create      => 1
});

if (!$EdgeID) {
    $Log->Message('ERROR', "Error Finding Edge");
}

FindEdgeProperty

Retrieves an edge property and returns the value.

If the Create option is set to true (1):

FindEdgeProperty(\%options)

Options

NDB         -> Neo4j database handle reference, (for example, \$NDB).
EdgeID      -> Edge ID for properties
EdgeType    -> (Optional) Edge Type
VertexType1 -> (Optional) Start Vertex Type
VertexType2 -> (Optional) End Vertex Type
Name        -> Property Name
Value       -> (Optional) Property Value
Create      -> (Optional) Set to 1 to create the property if it does not exist, or to update its value. Set to 0 otherwise.

Returns

1. ErrorFlag   (0 Good, 1 Bad)
2. Message     (String)
3. Property Value or undef if not created or updated

Synopsis

Set:

my ($ErrorFlag, $Message) = FindEdgeProperty({
    NDB     => \$NDB,
    EdgeID  => $EdgeID,
    Name    => "Key",
    Value   => "Value",
    Create  => 1
});

if ($ErrorFlag) {
    $Log->Message('ERROR', "Error Setting Edge Property: $Message");
}

Get:

my ($ErrorFlag, $Message, $Value) = FindEdgeProperty({
    NDB     => \$NDB,
    EdgeID  => $EdgeID,
    Name    => "Key"
});

if ($ErrorFlag) {
    $Log->Message('ERROR', "Error Getting Edge Property: $Message");
}

FindEdgeTypeName

Finds the edge type name for the edge type that matches the type ID.

FindEdgeTypeName(\%options)

Options

NDB          -> Neo4j database handle reference, (for example, \$NDB).
StorageHash  -> Cache (for example, $StorageHash)
TypeID       -> Edge Type ID

Returns

1. ErrorFlag      (0 Good, 1 Bad)
2. Message        (String)
3. Edge Type name (String) or undef if not created

Synopsis

my ($ErrorFlag, $Message, $EdgeTypeName) = FindEdgeTypeName({
    NDB          => \$NDB,
    StorageHash  => $StorageHash,
    TypeID       => $EdgeTypeID
});

if (!$EdgeTypeName) {
    $Log->Message('ERROR', "Error Finding Edge Type: $Message");
}

OR

my $EdgeTypeName = FindEdgeTypeName({
    NDB          => \$NDB,
    StorageHash  => $StorageHash,
    TypeID       => $EdgeTypeID
});

if (!$EdgeTypeName) {
    $Log->Message('ERROR', "Error Finding Edge Type");
}

FindEdgeTypeID

Finds the edge type that matches the Name, LineStyle, and Direction. If the Create option is set to true (1), and no matching edge type exists, it will be automatically created.

FindEdgeTypeID(\%options)

Options

NDB          -> Neo4j database handle reference, (for example, \$NDB).
StorageHash  -> Cache (for example, $StorageHash)
Name         -> Edge Type Name
LineStyle    -> "Solid", "Dashed" or "Dotted"
Direction    -> Edge data direction (0=Non-Directed, 1=Directed)
Create       -> (Optional) Set to 1 to create the edge type if it does not exist, set to 0 otherwise.

Returns

1. ErrorFlag    (0 Good, 1 Bad)
2. Message      (String)
3. Edge Type ID (Integer) or undef if not created or updated

Synopsis

my ($ErrorFlag, $Message, $EdgeTypeID) = FindEdgeTypeID({
    NDB          => \$NDB,
    StorageHash  => $StorageHash,
    Name         => "My Edge Type",
    LineStyle    => "Solid",
    Direction    => 0,
    Create       => 1
});

if (!$EdgeTypeID) {
    $Log->Message('ERROR', "Error Finding Edge Type: $Message");
}

OR

my $EdgeTypeID = FindEdgeTypeID({
    NDB          => \$NDB,
    StorageHash  => $StorageHash,
    Name         => "My Edge Type",
    LineStyle    => "Solid",
    Direction    => 0,
    Create       => 1
});

if (!$EdgeTypeID) {
    $Log->Message('ERROR', "Error Finding Edge Type");
}

FindVertexByDevice

Finds a vertex ID by device arguments (for example, DeviceID, DNS name, or IP address). If the Create option is set to true (1), and no matching vertex exists, it will be automatically created.

FindVertexByDevice(\%options)

Options 

DBH          -> Assure1 database handle reference, (for example, \$DBH)
NDB          -> Neo4j database handle reference, (for example, \$NDB).
StorageHash  -> Cache (for example, $StorageHash)
DNS          -> DNS for lookup
IP           -> IPv4 address for lookup
IPv6         -> IPv6 address for lookup
CustomName   -> Custom Name for lookup
Create       -> (Optional) Set to 1 to create the vertex if it does not exist, set to 0 otherwise.
VertexName   -> VertexName to use with create

Returns

1. ErrorFlag (0 Good, 1 Bad)
2. Message   (String)
3. Vertex ID (String)

Synopsis

my ($ErrorFlag, $Message, $Vertex) = FindVertexByDevice({
   DBH          => \$DBH,
   NDB          => \$NDB,
   StorageHash  => $StorageHash,
   DNS          => "<DNSNAME>",
   IP           => "<IPADDRESS>",
   CustomName   => "<CUSTOMNAME>",
   VertexName   => "<VERTEXNAME>",
   Create       => 1,
});

FindVertexID

Finds a Vertex by the Name and Type and returns the ID of the Vertex if found. Searches only ParentID node's direct children. If the Create option is set to true (1), and no vertex with the specified name exists, it will be automatically created, but not linked.

FindVertexID(\%options)

Options

DBH         -> Assure1 database handle reference, (for example, \$DBH)
NDB         -> Neo4j database handle reference, (for example, \$NDB).
StorageHash -> Cache (for example, $StorageHash)
Name        -> Vertex Name
TypeID      -> Vertex Type ID
TypeName    -> (Optional) Vertex Type Name
ParentID    -> (Optional) Vertex ParentID (-1=any (first occurrence), 0=top-level. Defaults to -1)
Create      -> (Optional) Set to 1 to create the vertex if it does not exist, set to 0 otherwise. The default is 0.

Returns

1. ErrorFlag   (0 Good, 1 Bad)
2. Message     (String)
3. Vertex ID   (String) or undef if not found/created

Synopsis

my ($ErrorFlag, $Message, $VertexID) = FindVertexID({
    DBH         => \$DBH,
    NDB         => \$NDB,
    StorageHash => $StorageHash,
    Name        => "<VERTEXNAME>",
    TypeID      => $VertexTypeID,
    Create      => 1
});

if (!$VertexID) {
   $Log->Message('ERROR', "Error Finding Vertex: $Message");
}

OR

my $VertexID = FindVertexID({
   DBH         => \$DBH,
   NDB         => \$NDB,
   StorageHash => $StorageHash,
   Name        => "<VERTEXNAME>",
   TypeID      => $VertexTypeID,
   Create      => 1
});

if (!$VertexID) {
   $Log->Message('ERROR', "Error Finding Vertex");
}

FindLinkedVertices

Finds directly linked parents by the VertexID and EdgeType and returns a list containing a hash of each linked vertex.

FindLinkedVertices(\%options)

Options

NDB         -> Neo4j database handle reference, (for example, \$NDB).
VertexID    -> VertexID
Direction   -> (Optional) Edge data direction. (0=Non-Directed, 1=Direct Parents, 2=Direct Children) defaults to 1. Non-Directed returns list of any neighbors (parent or child), Direct Parent returns list of parents and Direct Children returns list of children.
TypeID      -> (Optional) Searches for neighbors/parents of a certain Vertex Type. If not given, searches for any vertex type.
VertexType  -> (Optional) Vertex Type. If TypeID is specified, TypeID will take precedence. If not given, searches for any vertex type.
EdgeTypeID  -> (Optional) Looks for neighbors/parents linked with the given Edge Type ID. If not given, searches for any edge type.
EdgeType    -> (Optional) Edge Type. If EdgeTypeID is specified, EdgeTypeID will take precedence. If not given, searches for any edge type.

Returns

1. ErrorFlag    (0 Good, 1 Bad)
2. Message      (String)
3. Parent Links (Array ref) or undef if error. Contains list of linked vertex info:
   * VertexID

Synopsis

my ($ErrorFlag, $Message, $Parents) = FindLinkedVertices({
    NDB         => \$NDB,
    VertexID    => $VertexID,
    Direction   => 1
});

if ($ErrorFlag) {
   $Log->Message('ERROR', "Error Finding Parents: $Message");
}

OR

my $Parents = FindLinkedVertices({
    NDB         => \$NDB,
    VertexID    => $VertexID,
    Direction   => 1
});

if (!$Parents) {
   $Log->Message('ERROR', "Error Finding Parents");
}

FindVertexProperty

Retrieves a vertex property and returns the value. If the Create option is set to true (1):

FindVertexProperty(\%options)

Options

NDB         -> Neo4j database handle reference, (for example, \$NDB).
VertexID    -> Vertex ID for properties
VertexType  -> (Optional) Vertex Type
Name        -> Property Name
Value       -> (Optional) Property Value
Create      -> (Optional) Set to 1 to create the property if it does not exist, or to update its value. Set to 0 otherwise.
StorageHash -> Cache (for example, $StorageHash)

Returns

1. ErrorFlag   (0 Good, 1 Bad)
2. Message     (String)
3. Property Value or undef if not created/updated

Synopsis

Set:

my ($ErrorFlag, $Message) = FindVertexProperty({
    NDB       => \$NDB,
    VertexID  => $VertexID,
    Name      => "Key",
    Value     => "Value",
    Create    => 1
});

if ($ErrorFlag) {
    $Log->Message('ERROR', "Error Setting Vertex Property: $Message");
}

Get:

my ($ErrorFlag, $Message, $Value) = FindVertexProperty({
    NDB       => \$NDB,
    VertexID  => $VertexID,
    Name      => "Key"
});

if ($ErrorFlag) {
    $Log->Message('ERROR', "Error Getting Vertex Property: $Message");
}

FindVertexTypeID

Finds a vertex type by Name and icon path. If the Create option is set to true (1), and no matching vertex type exists, it will be automatically created.

FindVertexTypeID(\%options)

Options

NDB         -> Neo4j database handle reference, (for example, \$NDB).
StorageHash -> Cache (for example, $StorageHash)
Name        -> Vertex Type Name
IconPath    -> Vertex Icon path (relative to the icons directory)
Create      -> Set to 1 to create the vertex type if it does not exist, set to 0 otherwise.

Returns

1. ErrorFlag      (0 Good, 1 Bad)
2. Message        (String)
3. Vertex Type ID (Integer) or undef if not created

Synopsis

my ($ErrorFlag, $Message, $VertexTypeID) = FindVertexTypeID({
    NDB         => \$NDB,
    StorageHash => $StorageHash,
    Name        => "<VERTEXTYPENAME>",
    IconPath    => "/images/Info.png"
    Create      => 1
});

if (!$VertexTypeID) {
    $Log->Message('ERROR', "Error Finding Vertex Type: $Message");
}

OR

my $VertexTypeID = FindVertexTypeID({
    NDB         => \$NDB,
    StorageHash => $StorageHash,
    Name        => "<VERTEXTYPENAME>",
    IconPath    => "/images/Info.png"
    Create      => 1
});

if (!$VertexTypeID) {
    $Log->Message('ERROR', "Error Finding Vertex Type");
}

FindVertexTypeName

Finds the name of the vertex type that matches the specified vertex type ID.

FindVertexTypeName(\%options)

Options

NDB          -> Neo4j database handle reference, (for example, \$NDB).
StorageHash  -> Cache (for example, $StorageHash)
TypeID       -> Vertex Type ID

Returns

1. ErrorFlag    (0 Good, 1 Bad)
2. Message      (String)
3. Vertex type name (String) or undef if not created

Synopsis

my ($ErrorFlag, $Message, $VertexTypeName) = FindVertexTypeName({
    NDB          => \$NDB,
    StorageHash  => $StorageHash,
    TypeID       => VertexTypeID
});

if (!$VertexTypeName) {
    $Log->Message('ERROR', "Error Finding Vertex Type: $Message");
}

OR

my $VertexTypeName = FindVertexTypeName({
    NDB          => \$NDB,
    StorageHash  => $StorageHash,
    TypeID       => VertexTypeID
});

if (!$VertexTypeName) {
    $Log->Message('ERROR', "Error Finding Vertex Type");
}

GetNDBConnection

Opens a connection to Neo4j. If $NDB is already defined, simply returns $NDB. Otherwise, attempts to establish a new connection.

GetNDBConnection(\%options)

Options

NDB      -> Neo4j database handle reference, (for example, \$NDB).
Expire   -> Expiry time for JWT token. Defaults to 3600 seconds (1 hour)

Returns

NDB      Neo4j database handle reference,

GetVertexInfo

Obtains a vertex's information, such as Name, Vertex Type, and Properties.

GetVertexInfo(\%options)

Options

NDB         -> Neo4j database handle reference, (for example, \$NDB).
StorageHash -> Cache (for example, $StorageHash)
VertexID    -> Vertex ID
VertexType  -> (Optional) Vertex Type

Returns

1. ErrorFlag      (0 Good, 1 Bad)
2. Message        (String)
3. Vertex Info (Hash ref) or undef if not found

Synopsis

my ($ErrorFlag, $Message, $VertexInfo) = GetVertexInfo({
    NDB         => \$NDB,
    StorageHash => $StorageHash,
    VertexID    => $VertexID
});

if ($ErrorFlag) {
    $Log->Message('ERROR', "Error Finding Vertex Info: $Message");
}

OR

my $VertexInfo = GetVertexInfo({
    NDB         => \$NDB,
    StorageHash => $StorageHash,
    VertexID    => $VertexID
});

if (!$VertexInfo) {
    $Log->Message('ERROR', "Error Finding Vertex Info");
}