Events Examples

The Oracle Communications Unified Assurance Fault Management platform aggregates and correlates fault and event information. The platform has many applications that are capable of receiving, processing, and enriching events in any format, from virtually any device. The applications actively process events to isolate and pinpoint the underlying cause of a problem. Advanced correlation tools are available and can use topological information to correlate events. You can easily make adjustments with the default de-duplication and highly customizable rules engine.

This topic provides examples of setting up event monitoring and management by:

Enabling and Starting Event Collection Aggregators
Viewing the Event List
Creating Custom Event Filters
Creating Custom Event Menus and Tools
Viewing and Editing Rules
Creating Custom Mechanizations
Viewing Logs and Changing Log Levels
Creating Custom Watcher Policies
Configuring Custom Actions with CAPE Policies

Enabling and Starting Event Collection Aggregators

This procedure describes how to enable and start the trap and syslog aggregators to receive traps for event monitoring. The Event Trap Aggregator service is a generic SNMP trap message listener and the Event Syslog Aggregator service is a generic syslog message listener. Both services receive messages from devices, parse the results with customizable rules, and create de-duplicated events within Unified Assurance. By default, syslog messages are sent in a carriage return delimited format.

From the Configuration menu, select Broker Control, and then Services.

See Services in Unified Assurance User's Guide for information about this UI.
Select the Event Trap Aggregator service.

The Service (Edit) form appears.
Change Status to Enabled.
Optionally, depending on the server specifications and loads, increase the number of threads in the Threads field. As a starting point, use three times the number of CPU cores.
Click Submit.
Select the Event Syslog Aggregator service.

The Service (Edit) form appears.
Change Status to Enabled.
Click Submit.
Ctrl-click to select both the Event Trap Aggregator and Event Syslog Aggregator services.
Click Start.

If traps and syslogs are not reaching Unified Assurance, check your firewall settings. By default, devices send SNMP trap messages on UDP port 162 and syslog messages on UPD port 514. These ports must be opened in your firewall for Unified Assurance to receive messages. See Opening Ports in Unified Assurance Installation Guide for information about which ports to open.

Viewing the Event List

After you start the aggregator services, they listen on their respective ports for incoming events, which they save to the Event database.

You view the events in event lists, either in dashboards or in the Events UI. You filter the events that appear in lists with event filters. You can use the default event filters, customize them, or create your own.

To view the main event list in the Events UI:

From the main navigation menu, select Events.
Expand the Filters by Group: Global folder and select the All Events filter.

The event list appears, with all events for devices that forward SNMP trap and syslog events.

See Interacting with the Event List in Unified Assurance Concepts for more information about ways you can interact with the event list.

Creating Custom Event Filters

You can create custom event filters or customize the default event filters. You can control which users and user groups can access each filter.

For example, to create a filter to display all critical severity events that have not been acknowledged:

From the Configuration menu, select Events, and then Filters.

See Filters in Unified Assurance User's Guide for information about this UI.
Click Add.

The Filter (new) form appears.
In Name, enter Unacknowledged Critical.
Select a default display.
Leave User Owner and Group Owner with their default settings. This lets all users and groups see the filter.

If you set User Owner to a specific user, the filter appears under their Private Filters folder in the list of filters on the Events UI.
In Filter Clause, enter the following:
```
Ack=0 AND Severity=5
```
This is the WHERE clause of the SQL select statement. Do not include the word WHERE.
Click Submit.
From the Configuration menu, select Events, and then Filter Groups.

See Filter Groups for information about this UI.
Select the Global filter group.

The Event Filter Group (edit) form appears.
In Filters, toggle from Selected to Available.
Double-click the new Unacknowledged Critical filter to add it to the group.
Click Submit.

You can now select the new Unacknowledged Critical filter in event lists. In the main Events UI, it appears under the Filters by Group: Global folder.

Creating Custom Event Menus and Tools

You can create custom event tools to run from the event list, specify a menu to display the tool, and create custom menus.

Tools can be:

SQL tools, which are based on SQL database queries.
View tools, which run scripts from the event list.

To create a custom tool and menu:

Create a custom SQL tool:
1. From the Configuration menu, select Events, and then Tools.
  
  See Tools in Unified Assurance User's Guide for information about this UI.
2. Click Add and select SQL Tool.
  
  The SQL Tool (New) form appears.
3. In Tool Name, enter Custom Escalate to Critical.
4. Optionally, from the Icon menu, select the flag_red icon.
5. In SQL, enter the following query:
```
UPDATE Events SET Severity=5 WHERE Severity !=5 AND EventID IN ($EVENTLIST);
```
  This query uses the EventID of the selected event, searches for it in the Events table in the Event database, and updates the Severity field to 5 (Critical).
6. Click Submit.
Create a custom menu for the custom tool:
1. From the Configuration menu, select Events, and then Menus.
  
  See Menus in Unified Assurance User's Guide for information about this UI.
2. Click Add.
  
  The Event Menu (new) form appears.
3. In Name, enter Custom Menu.
4. From User Group Name, select Administrators.
5. From the Tools list, double-click the new Custom Escalate to Critical tool you just created and click Add.
6. Click Submit.
Find and use the new tool:
1. Click the Unified Assurance logo to refresh the UI.
2. From the main navigation menu, click Events.
3. Expand the Filters by Group folder and select the All Events filter.
4. Right-click a low-severity event to see the new Custom Menu in the list of tools and menus.
5. From Custom Menu, select your new Custom Escalate to Critical tool.
  
  The severity of the event changes to critical.

Viewing and Editing Rules

In Unified Assurance, the Trapd and Syslog Aggregator rules files process raw trap data and syslog messages and determine the output to the Event database and event list.

To see the rules:

From the Configuration menu, select Rules.

See Rules in Unified Assurance User's Guide for information about this UI.

The list of rules directories and subdirectories appears. Click the triangle icon beside the directory to expand or collapse it.
Expand Core Rules (core), then Default read-write branch (default), then collection, then event, and then trap or syslog.
Click any rules file.

The Rule (edit) form appears with the rule.

Rules are separated into the following file types:

Load rules: The default file is base.load. This file is loaded and run once when the poller or aggregator starts. It preloads enrichment data that can be used throughout the rules files. You can define hashes, run SQL lookups, and define any other variables to use throughout the rules. The trap base.load file also includes the code necessary for:
- Correct functioning of extended rules.
- Optional support for event maintenance windows (commented out by default).
- Optional support for priority scoring (commented out by default).
Include rules: The default file is base.includes. This file contains a list of any additional rules files you have in your rules repository that you wish to run. The default trap base.includes file contains:
```
CustomerRules,collection/event/common/aggregators/customer.rules
```
The default syslog base.includes file contains:
```
TopologyConfigRules,collection/event/syslog/config_manager.rules
CustomerRules,collection/event/common/aggregators/customer.rules
CiscoRules,collection/event/syslog/cisco.rules
```
The customer.rules file is run at the end of base.rules for each event, after all other include rules have run. It is not specific to any one aggregator; you can use it for common event rules that apply to all aggregators.

You can add lines for more files in base.includes using the following format: <NameOfSubfunctionToCreate>,<PathRelativeToA1BASEDIR>/<filename>.rules

You can create rules file in the trap or syslog directories and run the rules file by calling the subfunction name defined in base.includes.
Base rules: The default file is base.rules. This file runs for each trap or syslog message received. The base rules for Trapd run the foundation rule for the trap based on the trap OID. You can define additional rules for generic or specific trap values, add them to base.includes, and reference their subfunction in BaseRules.

Process Order for Trapd Rules

To apply rules, Trapd does the following:

Loads the base rules file into memory.
Loads the load rules file into memory.
Parses the include rules file and loads files referenced within into memory.
Runs load rules.
Runs base rules for each event.
Runs files referenced in base.includes when invoked in the base rules.
Runs customer.rules for each event after include rules are finished running.

The Trapd Aggregator application configuration defines which files contain the base rules, include rules, and load rules, and other settings. You can see and edit the application configuration using the Services UI. From the Configuration menu, select Broker Control, and then Services. See Trapd for more information about this aggregator and Services in Unified Assurance User's Guide for information about the Services UI.

Creating Custom Rules Files

You can create custom Unified Assurance rules files by converting vendor MIB files using the Unified Assurance Common Object Model (COM) SDK. See COM Overview for information.

Creating Custom Mechanizations

Mechanizations are MySQL stored procedures that perform scheduled tasks like facilitating event correlation and deleting expired events.

The following example shows how to create a mechanization that deletes cleared (green) events that are over 60 minutes old. It is similar to the default mechanization that deletes expired events.

From the Configuration menu, select Events, then Processing, and then Mechanizations.

See Mechanizations in Unified Assurance User's Guide for information about this UI.
Click Add.

The Mechanization (new) form appears.
In Name, enter DeleteCleared.
Schedule the mechanization to run every ten minutes by setting Minutes to 0,10,20,30,40,50 and all other time fields to *.
Set Status to Enabled.

In Stored Procedure, enter the following:

DECLARE Done int default 0;
    DECLARE StartTime decimal(13, 3) unsigned default UNIX_TIMESTAMP(NOW(3));
    DECLARE StopTime decimal(13, 3) unsigned;
    DECLARE RowCount int default 0;
    DECLARE DeleteEventID bigint;
    DECLARE DeleteLastReported decimal(13, 3) unsigned;
    DECLARE Deletes CURSOR FOR
SELECT EventID,
       LastReported
FROM Events
WHERE LastReported < (UNIX_TIMESTAMP() - 3600)
  AND Severity = 0;
DECLARE CONTINUE HANDLER FOR SQLSTATE '02000' SET Done = 1;
OPEN Deletes;
REPEAT
FETCH Deletes
         INTO DeleteEventID,
              DeleteLastReported;
        IF NOT Done THEN
            SET RowCount = RowCount + 1;
UPDATE IGNORE Events
SET Action      = 'DeleteCleared',
    Actor       = 'EventMechanization',
    Duration    = UNIX_TIMESTAMP(NOW(3)) - FirstReported,
    LastChanged = UNIX_TIMESTAMP(NOW(3))
WHERE EventID     = DeleteEventID;
DELETE IGNORE FROM Events
                         WHERE EventID = DeleteEventID;
END IF;
    UNTIL Done END REPEAT;
CLOSE Deletes;
SET StopTime = UNIX_TIMESTAMP(NOW(3));

Click Submit.

Viewing Logs and Changing Log Levels

You can use the Trapd and Syslog logs for debugging and troubleshooting. By default, the aggregators write to log files under the $A1BASEDIR/logs/ directory. You can view the log files directly in this directory, or you can view, filter, and search log messages in the Logs UI.

The default logging level is ERROR, which means that only errors will be written to the logs, but you can increase or decrease the logging level for debugging and troubleshooting.

The following example shows how to increase the log level for the Trapd Aggregator to DEBUG, which writes all error, warning, info, and debug information to the logs.

To increase the log level and view the log messages in the Logs UI:

From the Configuration menu, select Broker Control, and then Services.

See Services in Unified Assurance User's Guide for information about this UI.
Select the Event Trap Aggregator service.

Tip:

You can use the filter bar to filter the services by name and find the service more quickly.
In Configuration, change the value of LogLevel to DEBUG.
Click Submit.
Select the Event Trap Aggregator service again.
From the button bar, click Restart.

The service is restarted and the new configuration takes effect.
From the main navigation, click Logs.

The Logs UI appears.
In the search bar, enter the following to filter the logs for those from Trapd:
```
app:Trapd
```

Creating Custom Watcher Policies

Watcher policies poll for certain events within a specified time period, and trigger synthetic meta events depending on the poll results. For example, the default watcher policies send an event when there have been no syslog messages from a device in 15 minutes and when a user has three failed login attempts within 15 minutes. You can modify the default policies, or create new ones.

To create and enable a watcher policy:

Create a custom meta event for the custom watcher policy to trigger:
1. From the Configuration menu, select Events, then Processing, and then Meta Events.
  
  See Meta Events for information about this UI.
2. Select the default Login Failure x3 event and click Clone.
  
  The Meta Event (edit) form appears.
3. In any fields where 3 is used, replace 3 with 5. For example, change the Name field to Login Failure x5
4. Click Submit.
Create the custom watcher policy:
1. From the Configuration menu, select Events, then Processing, and then Watcher Policies.
  
  See Watcher Policies for information about this UI.
2. Select the default Login Failure x3 watcher policy and click Clone.
  
  The Watcher Policy (new) form appears.
3. In Name, enter Login Failure x5.
4. In Description, change Sum of Count >= 3 to Sum of Count >= 5.
5. Set State to Enabled.
6. In Threshold, change Value to 5.
7. In Action, change Meta Event to Login Failure x5
8. Click Submit.
Enable and start the Event Watcher service:
1. From the Configuration menu, select Broker Control, and then Services.
  
  See Services for information about this UI.
2. Select the Event Watcher service.
3. Set Status to Enabled.
4. Click Submit.
5. Select the Event Watcher service again.
6. From the button bar, click Start.

The Event Watcher service starts watching for login failures, and creates a Login Failure x5 event if anyone fails five login attempts in 15 minutes.

Configuring Custom Actions with CAPE Policies

The Custom Action Policy Engine (CAPE) Service runs policies that trigger custom Perl code that performs custom actions. You use CAPE policies to perform special processing based on information from within the Unified Assurance database. However, nodes are not limited to Unified Assurance information only. CAPE policies query the Unified Assurance database at a defined poll interval and, if the query returns a value, the policies trigger CAPE nodes, which are defined within the policy. The CAPE node contains Perl-based logic to perform custom actions on the data returned by the CAPE policy.

The process of implementing CAPE policies is:

Optionally, create a CAPE-specific device zone. This is not required, but recommended. See About CAPE Device Zones for more information.
Create a CAPE node to perform the custom actions.
Create a CAPE policy to select the events to perform the actions on.
Create a custom CAPE service to run the node. The examples assume a single database shard, but if you are using multiple shards, create a custom service for each shard.

About CAPE Device Zones

Oracle recommends creating CAPE-specific device zones to use with your CAPE implementation. These are not regular devices zones; you do not add devices to these zones, and they do not restrict the devices or events that the policies apply to. Instead, you select these zones when creating CAPE policies and services so that you can generate unique log files for each policy, and have greater flexibility in stopping, starting, and managing policies.

By default, CAPE policies are applied to all zones. Without CAPE-specific zones, if you have multiple CAPE services and policies, each service runs all of the policies. This can result in unnecessary repetition of work, performance issues, or server failure. For example, if you have five CAPE services and ten CAPE policies in the default zone, each service will run each policy, so all ten policies will run five times. By instead using distinct, CAPE-specific zones, you can specify which service runs which policy. This lets you run only the relevant policies and avoid repetition that could overburden your servers.

Oracle recommends setting up one CAPE zone for each CAPE service, and one CAPE service for each set of chained nodes and policies. For example, you might have:

A zone and service for a single node and policy: Zone A, service A, node A, and policy A
A zone and service for multiple linked nodes and policies: Zone B, service B, nodes B and C, policies B, C, and D
A zone and service for multiple linked nodes and one policy: Zone C, service C, nodes E and F, policy E
A zone and service for one node and multiple policies: Zone D, service D, node G, policies F and G

Example CAPE Policy for Device Down Events

This example shows how to create a CAPE policy and node that check threshold violation events to see if a device is reachable or not. It assumes that the Ping Latency Poller and Standard Thresholding Engine services are running.

Create the CAPE device zone:
1. From the Configuration menu, select Device Catalog, and then Device Zones.
  
  See Device Zones in Unified Assurance User's Guide for information about this UI.
2. Click Add.
3. In Name, enter CAPE Device Down.
4. Click Submit.

Create the CAPE node:

From the Configuration menu, select Events, then CAPE, and then Nodes.

See Nodes in Unified Assurance User's Guide for information about this UI.
Click Add.

The CAPE Node (new) form appears.
In Name, enter CAPE Device Down.
Optionally, enter a description.

In Node Text, add the following code:

# Grab the values selected in the SELECT statement used in the CAPE policy. Only things referenced in the CAPE policy's SQL SELECT statement are available to the CAPE node.
my $EventID   = $EventData->{'EventID'};
my $IPAddress = $EventData->{'IPAddress'};
my $Severity  = $EventData->{'Severity'};

# Attempt to ping the device and store the result in the $ping variable. The CAPE policy's SQL SELECT statement pulls only Device Down events, which are created by the threshold engine for the Device Down threshold. 
$Log->Message("DEBUG", "Running Ping check command");
my $ping = `ping -c10 $IPAddress`;
$Log->Message("DEBUG", "Result of Ping test ----> [ $ping ]");

# If the result of the ping contains the text 'ttl', the ping was successful. Set the event severity to '0' (cleared) and save a log message to the CAPE log. If the ping failed, set the event severity to '5' (critical).
if ($ping =~ m/ttl/i){
   $Log->Message("DEBUG", "Result of Ping Test SUCCESSFUL - suppressing event");
   $Severity = 0;
}
else {
   $Log->Message("DEBUG", "Result of Ping Test failed, escalating event");
   $Severity = 5;
}

# Create a journal entry for the EventID with the output of the ping from the previous step.
$Log->Message("DEBUG", "Inserting into Journal [$EventID:$ping]");
my ($ErrorFlag, $Message) = AddJournal({
    DBH       => $EventDBH,
    EventID   => $EventID,
    TimeStamp => time(),
    Username  => '1',
    Entry     => $ping,
    ShardID   => $AppConfig->{'ShardID'}
});

# Update the event with new information. Update the severity if the ping was successful. This prevents CAPE redoing events it has previously acted upon. 
$Log->Message("DEBUG", "Updating event entry [$EventID:$Severity]");
my ($ErrorFlag, $Message) = UpdateEvent({
    DBH     => \$EventDBH,
    EventID => $EventID,
    Values  => {
        Severity => $Severity
    }
});

Click Submit.

Create a CAPE policy:
1. From the Configuration menu, select Events, then CAPE, and then Policies.
  
  See Policies in Unified Assurance User's Guide for information about this UI.
2. Click Add.
  
  The CAPE Policy (new) form appears.
3. In Name, enter CAPE Device Down.
4. Optionally, enter a description.
5. From the Zone menu, select the CAPE Device Down zone that you just created.
6. Set Event Grouping to Process Events Individually.
  
  This setting determines whether the returned data is processed individually (one row at a time), or together (all at once).
7. Set Poll Interval to 300.
  
  The policy will run against the event list every 5 minutes.
  
  Note:
  
  Make sure the poll interval is realistic for the amount of time the policy processing will take. Polling every 30 seconds when the process takes more than 30 seconds will result in errors.
8. In First Node Executed, select the CAPE Device Down node you just created.
9. Set State to Enabled.
10. In Event Select Statement, add the following code:
```
SELECT EventID, Severity, IPAddress
  FROM Events
 WHERE Severity   = 5
   AND EventType = "Device Down"
 LIMIT 10
```
11. Click Submit.
Create and start a custom CAPE service:
1. From the Configuration menu, select Broker Control, and then Services.
  
  See Services in Unified Assurance User's Guide for information about this UI.
2. Select the Event Custom Action Policy Engine (CAPE) service.
  
  Tip:
  
  You can use the filter bar to filter the services by name and find the service more quickly.
3. Click Clone.
4. In Name, enter CAPE Device Down.
5. Set Status to Enabled.
6. Under Configuration, set the following fields:
  1. Set the following fields:
    - LogFile: logs/CAPEDeviceDown.log
    - LogLevel: DEBUG
  2. Add the DeviceZoneID field and set it to CAPE Device Down.
7. Click Submit.

Example CAPE Policy for Enriching the DeviceType Field

This example shows how to create a CAPE policy and node to add information to the DeviceType field for events.

Create the CAPE device zone:
1. From the Configuration menu, select Device Catalog, and then Device Zones.
  
  See Device Zones in Unified Assurance User's Guide for information about this UI.
2. Click Add.
3. In Name, enter CAPE Enrich DeviceType.
4. Click Submit.
Create the blank CAPE node:
1. From the Configuration menu, select Events, then CAPE, and then Nodes.
  
  See Nodes in Unified Assurance User's Guide for information about this UI.
2. Click Add.
  
  The CAPE Node (new) form appears.
3. In Name, enter CAPE Enrich DeviceType.
4. Optionally, enter an alias and description. You can use the description of what this node does provided before this procedure.
5. Click Submit.
  
  The node is created.
  
  Note:
  
  You have not yet included any Perl code in the node. This mimics the iterative process of creating a real CAPE node and policy, where you create a blank node, then create a policy, and make continual refinements to the code in the policy and node until it works as desired.

Add code to the CAPE node:

Select the CAPE Enrich DeviceType node you just created.

In Node Text, add the following code, replacing <date> and <username> with appropriate values.

###########################################################################################################
# Perl Modules
use Data::Dumper;
use DBI;
###########################################################################################################
# Assure1 Modules
use Assure1::Config;
use Assure1::Core;
use Assure1::Events;
use Assure1::API;
###########################################################################################################
# Create database handles to connect to the Assure1 and Event databases.
our $Config  = Assure1::Config->new();
my $A1DBH    = DBConnect( $Config, 'Assure1', { AutoCommit => 1 } );
my $EventDBH = DBConnect( $Config, 'Event', { AutoCommit => 1 } );

# Extract relevant information from the $EventData hash
my $IPAddress  = $EventData->{IPAddress};
my $Node       = $EventData->{Node};
my $EventID    = $EventData->{EventID};
my $DeviceType = $EventData->{DeviceType};

# Log the extracted information
$Log->Message( 'DEBUG', [
        '#===================================',
        '# CAPE CPU Enrichment Event Values',
        '# IPAddress  = ' . $IPAddress,
        '# Node       = ' . $Node,
        '# EventID    = ' . $EventID,
        '# DeviceType = ' . $DeviceType,
        '#==================================='
] );

my $apiHandle = new Assure1::API; # Create an API handle for making API calls

my $trace = "CAPEEnrichDeviceType[$EventID]:"; # Create a unique identifier for this CAPE node and EventID.

###########################################################################################################
# MAIN
###########################################################################################################

$Log->Message( 'DEBUG', "$trace Starting..." );

# Check if $IPAddress is defined and not empty
if (defined $IPAddress && $IPAddress !~ /^\s*$/) {

    # First get the DeviceID using the FindDeviceID function
    my ( $ErrorFlag, $Message, $DeviceID ) = FindDeviceID( {
            DBH         => \$A1DBH,
            StorageHash => $StorageHash,
            IP          => $IPAddress
    } );

    $Log->Message( 'INFO', "FindDeviceID result: ErrorFlag=$ErrorFlag, Message=$Message, DeviceID=$DeviceID" );

    if (defined $DeviceID && $DeviceID !~ /^\s*$/) {

        # Then get SNMP info from the device using the FindDeviceID
        my ( $ErrorFlag, $Message, $DeviceInfo ) = GetDeviceByID( {
                DBH               => \$A1DBH,
                DeviceID          => $DeviceID,
                IncludeSNMPAccess => 1,
                IncludeMetaData   => 1,
                StorageHash       => $StorageHash
        } );

        if (defined $DeviceInfo && !$ErrorFlag) {

            $Log->Message( 'DEBUG', "$Message : Retrieved device info for $Node: DeviceID=$DeviceID, DeviceInfo :" . Dumper($DeviceInfo) );
            $Log->Message( 'INFO', "$Message : Retrieved SysObjectID for $Node: SysObjectID :" . $DeviceInfo->{'SysObjectID'} );

            if (defined $DeviceInfo->{'SysObjectID'} && $DeviceInfo->{'SysObjectID'} !~ /^\s*$/) {

                my $DeviceTypeSysObjectID = "id-" . $DeviceInfo->{SysObjectID};

            $Log->Message( 'INFO', "$Message : CallAPI SysObjectID :" . $DeviceTypeSysObjectID );

                my ($error, $result) = CallAPI({
                        handle => $apiHandle,
                        url    => '/api/device/types/' . $DeviceTypeSysObjectID,
                        method => 'read',
                        params => [],
                });

                $Log->Message( 'DEBUG', "CallAPI result for DeviceTypes: error=" . ( $error // 'undef' ) . ", result=" . Dumper($result) );

                    if ($error == 0 && defined $result && defined $result->[0]) {

                    $Log->Message( 'INFO', "CallAPI DeviceTypeCategoryName name : " . $result->[0]->{'DeviceTypeCategoryName'} );
                    $Log->Message( 'INFO', "CallAPI DeviceTypeVendorName name : " . $result->[0]->{'DeviceTypeVendorName'} );
                    $Log->Message( 'INFO', "CallAPI DeviceTypeName name : " . $result->[0]->{'DeviceTypeName'} );

                    $DeviceType = $result->[0]->{'DeviceTypeCategoryName'} .' : ' . $result->[0]->{'DeviceTypeVendorName'} . ' : ' . $result->[0]->{'DeviceTypeName'};

                    if (defined $DeviceType && $DeviceType !~ /^\s*$/) {

                        my ( $ErrorFlag, $Message ) = UpdateEvent( {
                            DBH     => \$EventDBH,
                            EventID => $EventID,
                            ShardID => 1,
                            Values  => {
                                DeviceType => $DeviceType,
                                Actor      => 'CAPE',
                                Action     => 'CAPE: CAPEEnrichDeviceType'
                            }
                        } );

                        $Log->Message( 'INFO', "UpdateEvent event with DeviceType result: ErrorFlag=$ErrorFlag, Message=$Message" );

                    } else {
                        $Log->Message( 'WARN', "DeviceType is empty or undefined. Skipping UpdateEvent." );
                    }
                } else {
                    $Log->Message( 'ERROR', "CallAPI failed or returned invalid result. Error: " . ($error // 'undefined') );
                }
            } else {
                $Log->Message( 'ERROR', "SysObjectID is empty or undefined for DeviceID: $DeviceID" );
            }
        } else {
            $Log->Message( 'ERROR', "Failed to get device info for DeviceID $DeviceID: $Message" );
        }
    } else {
        $Log->Message( 'WARN', "DeviceID is empty or undefined. Ending Processing." );
    }
} else {
    $Log->Message( 'WARN', "IPAddress is empty or undefined. Ending Processing." );
}

if (defined $DeviceType && $DeviceType eq 'Unknown') {
    $Log->Message( 'WARN', "Device not present in Device Catalog" );

    my ( $ErrorFlag, $Message ) = UpdateEvent( {
        DBH     => \$EventDBH,
        EventID => $EventID,
        ShardID => 1,
        Values  => {
            DeviceType => 'Device not found in Device Catalog',
            Actor      => 'CAPE',
            Action     => 'CAPE: CAPEEnrichDeviceType'
        }
    } );
}

$Log->Message( "DEBUG", "$trace Finished..." );

Click Submit.

Create a CAPE policy:
1. From the Configuration menu, select Events, then CAPE, and then Policies.
  
  See Policies in Unified Assurance User's Guide for information about this UI.
2. Click Add.
  
  The CAPE Policy (new) form appears.
3. In Name, enter CAPE EnrichDeviceType.
4. Optionally, enter a description.
5. From the Zone menu, select the CAPE Enrich DeviceType zone that you just created.
6. Set Event Grouping to Process Events Individually.
7. Leave Poll Interval set to 30.
  
  Note:
  
  Make sure the poll interval is realistic for the amount of time the policy processing will take. Polling every 30 seconds when the process takes more than 30 seconds to run will result in errors.
8. In First Node Executed, select the CAPE Enrich DeviceType node that you just created.
9. Set State to Enabled.
10. In Event Select Statement, add the following code:
```
SELECT
    IPAddress,
    EventID,
    Node,
    DeviceType
  FROM
    Events
  WHERE
    DeviceType = 'Unknown';
  LIMIT 10
```
11. Click Submit.
Create and start a custom CAPE service:
1. From the Configuration menu, select Broker Control, and then Services.
  
  See Services in Unified Assurance User's Guide for information about this UI.
2. Select the Event Custom Action Policy Engine (CAPE) service.
  
  Tip:
  
  You can use the filter bar to filter the services by name and find the service more quickly.
3. Click Clone.
4. In Name, enter CAPE Enrich DeviceType.
5. Set Status to Enabled.
6. Under Configuration, set the following fields:
  1. Set the following fields:
    - LogFile: logs/CAPEEnrichDeviceType.log
    - LogLevel: DEBUG
  2. Add the DeviceZoneID field and set it to CAPE Enrich DeviceType.
7. Click Submit.
8. Select the service you just created and click Start.

To verify the functionality:

Add the DeviceType column to an event display:
1. From the Configuration menu, select Events, and then Displays.
2. Select the display you want to add it to, such as the default event display.
3. Under Columns, for DeviceType, select Visible, deselect Editable, and optionally drag and drop it to appear in a different order.
4. Click Submit.
Check the event list:
1. From the main navigation menu, select Events.
2. Select an event filter that uses the event display you added the DeviceType column to.
3. Review the values in the DeviceType column:
  - When a device has a corresponding type in the device catalog, the value has the following format:
    
    <DeviceTypeCategoryName> : <DeviceTypeVendorName> : <DeviceTypeName>
  - When a device has no corresponding type in the device catalog, the value is Device not found in Device Catalog.
  - When the CAPE service has not yet processed the event, the value is Unknown.

Title and Copyright Information

Implementation Guide

G18224-01