Assure1::Events Perl library¶

Description¶

Implements the functions for Event rules.

Synopsis¶

use Assure1::Events;

AddJournal¶

Insert a new journal entry for a given EventID in the real-time events database.

AddJournal(\%options)

Options

DBH       -> Events Database Handle reference (i.e. \$EventDBH)
EventID   -> Event EventID to update
Username  -> Assure1 username
TimeStamp -> epoch time stamp of when the journal was created
Entry     -> Journal Message (no size limitations)
ShardID   -> (Optional) ShardID of Events (default: 1)

Returns

1. ErrorFlag    (0 Good, 1 Bad)
2. Message (String)
3. New Journal Entry ID (Integer) - undef on error

Synopsis

my ($ErrorFlag, $Message) = AddJournal({
    DBH       => \$EventDBH,
    EventID   => '1',
    TimeStamp => time(),
    Username  => 'admin',
    Entry     => 'New Entry',
    ShardID   => 1
});

AddVisionData¶

Adds information required to display event in Vision

AddVisionData(\%options)

Options

Event     -> Event reference (i.e. $Event)
Type      -> (Optional) Vision type, can be `dDevice`, `dLink`, `pLink` or `point`. Defaults to `dDevice`.
StartName -> (Optional) Vision Entity to associate event with (defaults to $Event->{Node} (required where Vision type is `pLink` and should be set to start device for link)
EndName   -> (Optional) Vision Entity to associate with end of link (required where Vision type is `pLink`)
LinkNode  -> (Optional) Assure1 Node name for pLink events. Generally not a device but reference to a link between devices, defaults to $Event->{Node} (required where Vision type is `pLink`)
Interface -> (Optional) Assure1 Instance name for Interface on start device for link events (required where Vision type is `dLink`)
Layer     -> (Optional) Vision layer the event will be added to. For `dDevice`, `dLink` and `point` events defaults to `unknown`,
                        required where Vision type is `pLink`.
Source    -> (Optional) Vision source ID representing this system (defaults to 1)

Returns

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

Synopsis

my ($Error, $Message) = AddVisionData({
    Event     => $Event,
    Type      => 'point',
    StartName => $Event->{Node},
    Layer     => 'Switch',
    Source    => 1
});

ConvertAlarmToEventFields¶

Converts Assure1v4 Alarm structure fields to Assure1v5 Event structure fields for rules.

ConvertAlarmToEventFields($Event)

Arguments

Event -> The structure which necessitates field conversion

Returns

Event -> Structure with all fields converted

Synopsis

my $Event = ConvertAlarmToEventFields($Event);

CreateEvent¶

Create a Meta Event in the real-time events database using a Meta Event ID.

CreateEvent(\%options)

Options

EventDBH    -> Events Database Handle reference (i.e. $EventDBH)
Assure1DBH  -> Assure1 Database Handle reference(i.e. $Assure1DBH)
EventID     -> Meta Event ID
Values      -> Name/Value Pairs to map to Meta Event Template
ShardID     -> (Optional) Event Database ShardID to send event data (defaults to 1)

Returns

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

Synopsis

my ($ErrorFlag, $Message) = CreateEvent({
    EventDBH   => \$EventDBH,
    Assure1DBH  => \$Assure1DBH,
    EventID     => 1,          # Generic Service Event
    Values      => {
        SERVICENAME => 'Critical Test',
        EventID     => '1',
        SERVICEID   => '1',
        STATE       => '1',
        TIMESTAMP   => time()
    },
    ShardID     => 1
});

CreateSLMFilter¶

Creates SLM Event Filter and returns the new ID.

CreateSLMFilter(\%options)

Options

DBH             -> Assure1 Database Handle Reference (i.e. \$DBH)
FilterName      -> SLM Filter Name
CompareField    -> Event Field to compare (exact name)
CompareMetric   -> Metric to perform on Event Field:
                       1 = COUNT
                       2 = SUM
                       3 = MIN
                       4 = MAX
                       5 = AVG
CompareOperator -> Threshold compare:
                       0 = '='
                       1 = '>'
                       2 = '>='
                       3 = '<'
                       4 = '<='
                       5 = '!='
CompareValue    -> Threshold Value (float)
Weight          -> Weight to give threshold
WhereClause     -> SQL to filter events for CompareMetric

Returns

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

Synopsis

my ($ErrorFlag, $Message, $SLMFilterID) = CreateSLMFilter({
    DBH             => \$DBH,
    FilterName      => "My SLM Filter",
    CompareField    => 'EventID',
    CompareMetric   => 1,
    CompareOperator => 1,
    CompareValue    => 0,
    Weight          => 1,
    WhereClause     => 'Severity = 5'
});
if (!$SLMFilterID) {
    $Log->Message('ERROR', "Error Creating SLM Filter: $Message");
}

OR

my $SLMFilterID = CreateSLMFilter({
    DBH             => \$DBH,
    FilterName      => "My SLM Filter",
    CompareField    => 'EventID',
    CompareMetric   => 1,
    CompareOperator => 1,
    CompareValue    => 0,
    Weight          => 1,
    WhereClause     => 'Severity = 5'
});
if (!$SLMFilterID) {
    $Log->Message('ERROR', "Error Creating SLM Filter");
}

DeleteEvent¶

Delete an event by EventID in the real-time events database.

DeleteEvent(\%options)

Options

DBH     -> Events Database Handle Reference (i.e. \$EventDBH)
EventID -> Event EventID to delete
ShardID -> (Optional) ShardID of Event (defaults to 1)

Returns

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

Synopsis

my ($ErrorFlag, $Message) = DeleteEvent({
    DBH     => \$EventDBH,
    EventID => 1,
    ShardID => 1
});

FindEventID¶

Retrieve all the EventIDs given a filter. Note: Does not support shards; use FindEventIDByShard instead

FindEventID(\%options)

Options

DBH    -> Events Database Handle Reference (i.e. \$EventDBH)
Filter -> Filter of which event EventIDs you want retrieved

Returns

1. ErrorFlag   (0 Good, 1 Bad)
2. Message     (String)
3. Array of EventIDs (Ref) - undef on error

Synopsis

my ($ErrorFlag, $Message, $EventRef) = FindEventID({
    DBH    => \$EventDBH,
    Filter => $Filter
});

if (!$EventRef) {
     $Log->Message('ERROR', "Error retrieving Events using Filter [$Filter]: $Message");
}

OR

my $EventRef = FindEventID({
    DBH    => \$EventDBH,
    Filter => $Filter
});

if (!$EventRef) {
     $Log->Message('ERROR', "Error retrieving Events using Filter [$Filter]");
}

FindEventIDByShard¶

Retrieve all the EventIDs and their associated shard given a filter.

FindEventIDByShard(\%options)

Options

DBH     -> Events Database Handle Reference (i.e. \$EventDBH)
Filter  -> Filter of which event EventIDs you want retrieved
ShardID -> (Optional) search only the specified ShardID for results (defaults to 0: all shards)

Returns

1. ErrorFlag   (0 Good, 1 Bad)
2. Message     (String)
3. Array of hashes containing EventID and ShardID (Ref) - undef on error

Synopsis

my ($ErrorFlag, $Message, $EventRef) = FindEventIDByShard({
    DBH     => \$EventDBH,
    Filter  => $Filter,
    ShardID => 1
});

if (!$EventRef) {
     $Log->Message('ERROR', "Error retrieving Events using Filter [$Filter]: $Message");
}

OR

my $EventRef = FindEventIDByShard({
    DBH     => \$EventDBH,
    Filter  => $Filter,
    ShardID => 1
});

if (!$EventRef) {
     $Log->Message('ERROR', "Error retrieving Events using Filter [$Filter]");
}

GetEventField¶

Retrieve a single field value given the EventID.

GetEventField(\%options)

Options

DBH     -> Events Database Handle Reference (i.e. $EventDBH)
EventID -> EventID of the Event you wish to retrieve
Field   -> Field Name of the Event column you wish to retrieve (i.e. Node)
ShardID -> (Optional) ShardID of Event (default: 1, 0 for all)

Returns

1. ErrorFlag    (0 Good, 1 Bad)
2. Message      (String)
3. Field Value - undef on error

Synopsis

my ($ErrorFlag, $Message, $EventHash) = GetEventField({
    DBH     => \$EventDBH,
    EventID => $EventID,
    Field   => $FieldName,
    ShardID => 1
});

if (!$EventHash) {
    $Log->Message('ERROR', "Error retrieving Event Field [$EventID:$FieldName]: $Message");
}

OR

my $EventHash = GetEventField({
    DBH     => \$EventDBH,
    EventID => $EventID,
    Field   => $FieldName,
    ShardID => 1
});

if (!$EventHash) {
    $Log->Message('ERROR', "Error retrieving Event Field [$EventID:$FieldName]");
}

GetEventHash¶

Retrieve all the fields in a name/value hash given the EventID.

GetEventHash(\%options)

Options

DBH     -> Events Database Handle Reference (i.e. \$EventDBH)
EventID -> EventID of the Event you wish to retrieve
ShardID -> (Optional) ShardID of Event (default: 1)

Returns

1. ErrorFlag    (0 Good, 1 Bad)
2. Message      (String)
3. Hash of Event in FieldName => Field Value pairings - undef on error

Synopsis

my ($ErrorFlag, $Message, $EventHash) = GetEventHash({
    DBH     => \$EventDBH,
    EventID => $EventID,
    ShardID => 1
});

if (!$EventHash) {
    $Log->Message('ERROR', "Error retrieving EventHash [$EventID]: $Message");
}

OR

my $EventHash = GetEventHash({
    DBH     => \$EventDBH,
    EventID => $EventID,
    ShardID => 1
});

if (!$EventHash) {
    $Log->Message('ERROR', "Error retrieving EventHash [$EventID]");
}

GetEventMetric¶

Retrieve event metric value given a metric operator & filter search criteria.

GetEventMetric(\%options)

Options

DBH     -> Events Database Handle Reference (i.e. \$EventDBH)
Metric  -> Metric Operator (i.e. "count(*)" or "avg(Severity)")
Filter  -> Filter Clause (i.e. "Severity > 0")
ShardID -> (Optional) search only the specified ShardID for results (defaults to 0: all shards)

Returns

1. ErrorFlag   (0 Good, 1 Bad)
2. Message     (String)
3. Value       (Number) - undef on error

Synopsis

my ($ErrorFlag, $Message, $Value) = GetEventMetric({
    DBH     => \$EventDBH,
    Metric  => $Metric,
    Filter  => $Filter,
    ShardID => 1
});

if (!$Value) {
    $Log->Message('ERROR', "Error retrieving EventMetric [$Metric : $Filter]: $Message");
}

OR

my $Value = GetEventMetric({
    DBH     => \$EventDBH,
    Metric  => $Metric,
    Filter  => $Filter,
    ShardID => 1
});

if (!$Value) {
    $Log->Message('ERROR', "Error retrieving EventMetric [$Metric : $Filter]");
}

GetJournals¶

Retrieve a list of journal entries for a given EventID in the real-time events database.

GetJournals(\%options)

Options

DBH     -> Events Database Handle Reference (i.e. \$EventDBH)
EventID -> Event EventID to update
ShardID -> (Optional) ShardID of Event (default: 1)

Returns

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

Synopsis

my ($ErrorFlag, $Message, @JournalsArray) = GetJournals({
    DBH     => $EventDBH,
    EventID => 1,
    ShardID => 1
});

StoreValue¶

Set or Retrieve a name/value pair in the Storage Hash.

StoreValue(\%options)

Options

Store -> Thread Safe Custom Hash reference to share/save data
Name  -> Value Reference Name (required)
Value -> Value of Reference Name (required to Set)

Returns

1. Value

Synopsis

# Set
StoreValue({
    Store => $StorageHash,
    Name  => '123',
    Value => 'Test Data'
});

# Get
my $Value = StoreValue({
    Store => $StorageHash,
    Name  => '123'
});

UpdateEvent¶

Update a field set given an EventID in the real-time events database.

UpdateEvent(\%options)

Options

DBH     -> Events Database Handle Reference (i.e. \$EventDBH)
EventID -> Event EventID to update
Values  -> Field Name/Value Pairs to update in the event (all other field will be untouched)
ShardID -> (Optional) ShardID of Event (defaults to 1)

Returns

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

Synopsis

my ($ErrorFlag, $Message) = UpdateEvent({
    DBH     => \$EventDBH,
    EventID => 1,
    ShardID => 1,
    Values  => {
        Node    => 'localhost',
        Summary => 'New Status'
    }
});