Cisco Catalyst Center - Event Management - Getting Started Cisco Catalyst Center Event Management: Overview and Configuration

Cisco Catalyst Center - Event Management

Understanding Events

Catalyst Center Events are incidents such as loss of connectivity, device unavailability, internal system error, or thresholds met or exceeded. Catalyst Center Platform Events are a subset of Catalyst Center Assurance issues.

Catalyst Center Platform provides a framework to store and deliver notification of Events. Information about each occurrence can be learned using just the Catalyst Center GUI, or in combination with the Developer Toolkit API (Intent API). Information is displayed directly in the GUI, using synchronous API requests, or by establishing asynchronous notification to API notification endpoint(s) or email address(es).

For each selected event, notification may be configured to be done by email, or via a REST API call to an external REST-based Event listener. Once an Event is configured in this way it is said to be subscribed by a notification listener. When subscribed by email, when a selected event occurs, an email message is sent. When subscribed for API notification, if a selected event is detected, a REST API POST or PUT call is made by the Catalyst Center to the event listener with a JSON payload providing detailed event information. Notification via a REST API method provided by the requestor is commonly referred to as webhook callback or sometimes just webhooks.

Catalyst Center has significantly improved the Event Notification framework. Clients now receive rapid lightweight client notifications with minimal latency. Issue 'enrichment' API methods, previously available in another package have been added to Intent API to support drill-down in order to access additional information with recommended mitigation and hosts affected. Synchronous methods have been added to provide information on past Event occurrence.

Terminology: The term 'registered events' is used in the Catalyst Center GUI. This document drops the modifier 'registered' as all events available to users are 'registered'.

Event Definitions

Events are defined with attributes that include a textual description, a domain/subdomain classification, Type, *Category, *Severity, and Workflow Event attributes can be viewed and edited in the Catalyst Center GUI at Platform > Manage > Configurations > General Settings > Event Settings. Event attributes are set internally and not administrator modifiable.

Domains and Subdomains:

Domains and subdomains identify the internal service component defining the Event and initiating the notification. These use the same classifications taxonomy as is used by the Intent API.

Type, Category, Severity, Workflow

Values of Type, *Category, *Severity, or Workflow are attached to each defined Event.

Timestamp Unix Epoch millisecond format (time since Jan 1, 1970, in milliseconds), expressed as 13-digit base 10 values, Used for both request and response parameters,

Global Configuration Prerequisites

Email SMTP Configuration - For Notification by Email - (GUI Only)

Email SMTP configuration is required when configuring asynchronous notification by email.

At least one SMTP server along with from, to email address values must first be configured. This configuration is done in the Catalyst Center GUI in Settings (Gear icon) > System Settings > Settings > Email Configuration. Using the dialog, provide the SMTP Server: Hostname or IP address, Port, and username and password, if required. A secondary SMTP server may be specified. Then enter values for the sender, receiver, and a 'subject' line. These values will be used for all email delivered notifications.

For more information, see Catalyst Center Platform User Guide Release 2.3.7.x Configurations: Configure an Email Destination or the Configure Event Settings topic in your release Platform User Guide.

HTTP/S Proxy Gateway

When setting up for API notification by webhook callback, best practice is to first confirm HTTP/HTTPS network connectivity between your Catalyst Center and your event notification endpoint URI. If the notification URI is behind a firewall or proxy functioning as an HTTP/HTTPS gateway is is also good practice to review the Catalyst Center Proxy Server configuration found under System Settings > Settings > Proxy Config. (A SUPER-ADMIN-ROLE user is required to reconfigure these values.)

See Section: Configure System Settings > Configure the Proxy__ in the Cisco Catalyst Center Administrator Guide matching your deployed Catalyst Center release version.

Managing Event Definition Attributes (GUI Only)

Event definition attributes are assigned fixed values which can not be modified by a user through either the GUI or via API.

The Catalyst Center GUI, Platform > Manage > Configurations > Event Setting can be used to review, but not modify attribute values. It displays a table of defined Events along with a summary of each's values for Event Name, Domain, Type, Category, Severity, and Workflow. The 'Edit' action button should be ignored, as modifications to attribute values will be ignored,

For more information, see the Catalyst Center Platform User Guide, section Chapter Configurations: Configure Event Settings, or the correct dcoument version for your running version.

Notification / Subscription Management

To subscribe for notification of Event occurrences, provide either an email address or API endpoint for notification. This is done in either the Catalyst Center GUI or using the Catalyst Center Intent API Event Management domain methods.

Subscription Management (GUI)

Open Catalyst Center GUI Platform > Developer Toolkit > Events to display the table of defined Events. This table displays the first 10 events, ordered by Event ID. 'Show More' at the bottom of the table, will retrieve and add 10 more events at a time to the table. Rows already retrieved can be reordered by attribute by clicking on the corresponding column header. Use the Find control (upper right above the table) to filter a subset of Events by entering a substring of any field. For example, type "WARN" to see only Events categorized as WARN; or "Fan" to see only Events with the word "Fan" in the name or description. The Find control and other actions such as row reordering operate on Events retreived to the GUI, so best practice is to Show More until all Event definitions have been retrieved into the GUI table.

In the example below, the substring "DEVICES-3" returns four Events matching the EventId substring "NETWORK-DEVICES-3...".

Subscribe to An Event

Click the Event Name, to subscribe to an event, or to modify an existing subscription. This will open a dialog with tabs: 'Event Details', and 'Active Subscriptions'.

Event Details provides additional definition detail. The top two sections (GENERAL INFORMATION and TAGS) display values that will be delivered to the notification API. The bottom section (MODEL SCHEMA) provides the payload schema used to contain the delivered information.

GENERAL INFORMATION: Description, EventId, Namespace, Domain, Subdomain, Severity, Category, version, plus two fields used for additional information: "Catalyst Event link" and "Note".

• Catalyst Event Link: A URL, that when accessed, is redirected to a Catalyst Center Assurance page with Event details. (The link value displayed in the GUI is the suffix section of an API method link. The actual notification payload content will be a complete web address URL.)

• Note: A URL to the Developer Toolkit documentation page for the GET Issue Enrichment Details API method. (This value is identical for all Events.) This method may be used to query for additional information about the specific issue. See section Intent API GET Issue Enrichment Method below for more information.

• Namespace: Always "ASSURANCE". (Release 1.3.1)

• version: Always "1.0.0" (Release 1.3.1)

TAGS: All Events are tagged, minimally, with the "ASSURANCE" tag (Release 1.3.1). Each Event may have additional Tags. Tag assignments are not user configured.

MODEL SCHEMA: The JSON formatted schema for each Event definition is displayed at the bottom of the dialog, split into two tabbed sections. The "REST Schema" is the primary schema. "Details" expands 'Details' object referenced in the primary REST Schema. The Event Details page for the Event NETWORK-NON-FABRIC_WIRED-1-200" is shown below, followed by an expansion of its Primary schema and Details schema: .

Event "NETWORK-NON-FABRIC_WIRED-1-200" notification Primary Schema:

{
    "instanceId": "String",
    "eventId": "String",
    "name": "String",
    "namespace": "String",
    "description": "String",
    "type": "String",
    "category": "String",
    "severity": "Number",
    "timestamp": "Number",
    "domain": "String",
    "subDomain": "String",
    "source": "String",
    "context": "String",
    "details": "Object",
    "version": "String /*Default null*/",
    "tags": "Array",
    "ciscoDnaEventLink": "String",
    "note": "String",
    "tntId": "String /*Default null*/",
    "tenantId": "String /*Default null*/"
}

Event "NETWORK-NON-FABRIC_WIRED-1-200" notification Details Object Schema_ :

{
    "Type": "$eventSource$",
    "Assurance Issue Details": "This network device $nwDeviceName$ is unreachable from controller. The device role is $fabricOrDeviceRole$",
    "Assurance Issue Priority": "$priority$",
    "Device": "$eventUniqueId$",
    "Assurance Issue Name": "Network Device $entityId$ Is Unreachable From Controller",
    "Assurance Issue Category": "$category$",
    "Assurance Issue Status": "$status$"
}

Descriptors for field types (e.g. "String", "Number", or "Object") and for parameters (e.g. "$priority$") are replaced with specific values at the time of notification. See section Notification - Webhook API Schema and Payload in this document for a corresponding sample payload as delivered.

Reference: Cisco Catalyst Center Platform User Guide Chapter: Developer Toolkit GUI: Work with Event Notifications.

Intent API Event Management Methods

Catalyst Center Intent API Event Management methods may be used to perform many of the same Event Management actions as are done in the GUI. These methods also provide more details about an occurrence than provided through the GUI.

Intent API actions and queries include methods for queries for counts and lists of Event Definitions, including the payload and schema details, as well as methods to create/update/review/delete subscriptions for either API or email notification.

Synchronous query of past events is also supported. These methods can be used to obtain a history of occurrences which can be useful to learn of occurrences that took place when the delivery endpoint was not available or being monitored for any reason. Synchronous Event occurrence response schema and payload are similar to those delivered with asynchronous notification but have some differences and contains a different subset of information.

The Intent API Event Management Domain includes the following:

Event Methods:

• GET Event Count: Return the number of defined Events.
• GET Events: Obtain Event definition(s).

Subscription Methods:

• POST Subscription: Create one or more new event subscriptions.
• GET Subscriptions: Read information about one or more event subscriptions.
• PUT Subscription: Update one or more existing event subscriptions.
• DELETE Subscription: Delete one or more event subscriptions.
• GET Subscription Count: Get the number of existing subscriptions.

Synchronous Notification / Event-Series Methods:

• GET Event Series (Notification) Count: Return a count of Event occurrences matching request filter criteria.
• GET Event Series (Notification) Content: Get Event occurrence information matching request filter criteria.

Process Steps

Using the Catalyst Center GUI

Subscribe for Webhook API Notification using the GUI

1. Create a webhook API listener endpoint accessible from your Catalyst Center. Identify or confirm an appropriate API callback endpoint. These examples use webhook.site, a publicly available development site. Webhook.site generates unique endpoint along with a unique HTML webpage that parses and displays the received message. The API webhook URL will be of the form https://webhook.site/UNIQUE-URL, such as: https://webhook.site/d0f5ed2a-3ed3-464f-8a73-7b4416a108b1. The corresponding monitoring Webhook.Site GUI uses the same unique identifier of the form https://webhook.site/#!/UNIQUE-URL. Using Webhook.site, the testor sets default status response code, content type, timeout, reponse body, and variables. For this example, it is configured expect a POST and to return an HTTP/S response code of 200 (Success) with an empty response body.

2. Review and confirm that your Catalyst Center can send messages to your Event listener. Review values for *'Proxy Config', if necessary. (See HTTP/S Proxy Gateway for more information.)

3. Select the Event(s) to be subscribed. For this example, we'll use the Event "Switch Unreachable".

4. Open Catalyst Center GUI Platform > Developer Toolkit > Events. Click "Show More" until all defined Events have been loaded into the GUI. Scroll through the events until you see your selected Event, or use the Find control, entering a substring of the Event name.

5. Observe and record the associated Event ID. The Event Id for "Switch Unreachable" is "NETWORK-NON-FABRIC_WIRED-1-200". Click on the Event name field ("Switch Unreachable").

6. Observe and note the Event Attributes, Schema, and Details. Click on Subscribe (lower right). Enter subscription 'Name'. (This is a user-specified identifier. It should be a unique name for the Subscription space.)

7. Leave Subscription Type as "REST". Click "Create a new endpoint". Enter an endpoint name and description. These fields, like the Subscription name, are to help you identify this particular endpoint and are non-functional attributes.
   Enter authentication and trust certificate information as necessary for your endpoint. In this example, no trust certificate or authentication is required.
   
   Click on Subscribe to save.
   

8. Look for notification at your endpoint. See section Notification - Webhook API Schema and Payload, below.

Using the Intent API

Subscribe for Webhook API Notification (Intent API)

1. Follow steps 1. through 3. as above, in [Subscribe for Webhook API Notification using the GUI](#subscribe-for-webhook API Notification using the GUI).

2. Start an authenticated API session, using your preferred API development tool such as Postman or a scripting language such as Python. These examples use POSTMAN, an API development and collaboration tool. For more information on using POSTMAN with the Intent API see Cisco Catalyst Center Platform: Hello World. For more information on authentication, see API Quickstart and Getting Started with the Cisco Catalyst Center API: Authentication and Authorization. Subscription actions require authentication using a user role of NETWORK-ADMIN-ROLE, TELEMETRY-ADMIN-ROLE, or SUPER-ADMIN-ROLE.

   If you are using the Catalyst Center Developer Toolkit 'Try It' tool, you are operating in the authentication session of the GUI and do not have to re-authenticate.*)

3. Confirm API and Event accessibility and process by issuing a GET Events request. The 'tags' field must not be empty. Set this to "ASSURANCE". Optionally enter values for 'EventId' and other fields or leave them empty. In the example API call below, using POSTMAN, the address of the Catalyst Center is represented by variable {{dnac}}, the tag filter is set to ASSURANCE and a single EventId is specified: The response to this query returns the Event definition for a single Event, NETWORK-NON-FABRIC_WIRED-1-200. This confirms the availability of this Event for subscription.

4. Subscribe to this Event using a POST Subscription request. Subscription creation is requested via a POST with a JSON structured payload. In POSTMAN the request and header will look similar to the following:
   
   Add a request structure to the 'Body'. Note that this request structure is a subset of the request structure defined for this event. It omits 'subscriptionId', 'version' and 'instanceId' fields. (Parameters are indicated with double curly brackets ({{some_parameter}}. POSTMAN fills in these parameters when the request is sent. ).

   

A sample is shown below:

[
    {
        "name": "JRR-Demo-11-15.001",
        "description": "Postman API call generated",
        "subscriptionEndpoints": [
            {
                "subscriptionDetails": {
                    "name": "Endpoint 1",
                    "url": "https://webhook.site/d0f5ed2a-3ed3-464f-8a73-7b4416a108b1",
                    "method": "POST",
                    "connectorType": "REST"
                }
            }
        ],
        "filter": {
            "eventIds": [
                "NETWORK-NON-FABRIC_WIRED-1-200"
            ]
        }
    }
]

The response will be a status URL in the following form:

{
    "statusUri": "/dna/intent/api/v1/event/api-status/<instance_id>"
}

Such as:

{
    "statusUri": "/dna/intent/api/v1/event/api-status/7d4dcc5a-5624-47ac-9cfb-9012d32fd3c0"
}

Issue this API Status request query as a GET just as the others, by adding the hostIP prefix and including the authentication token.) In POSTMAN, this query and the response will look similar to the following:

5. Confirm the Subscription using GET Subscriptions We'll limit the requested response to just those subscriptions that are for the specific Event.
   The response will be a list of subscriptions (zero or more). In this case, there is just one subscription:

    [   {
        "version": null,
        "subscriptionId": "7b35927b-e0d5-4788-b372-015dec951f2e",
        "name": "JRR-Demo-11-15.001",
        "subscriptionEndpoints": [
            {
                "instanceId": "de1fc747-e3a7-4ff5-961d-5778be4ac370",
                "subscriptionDetails": {
                    "connectorType": "REST",
                    "instanceId": null,
                    "name": "Endpoint 1 ",
                    "description": null,
                    "connectorType": "REST",
                    "url": "https://webhook.site/d0f5ed2a-3ed3-464f-8a73-7b4416a108b1",
                    "basePath": null,
                    "resource": null,
                    "method": "POST",
                    "trustCert": false,
                    "headers": [],
                    "queryParams": [],
                    "body": null,
                    "connectTimeout": 10,
                    "readTimeout": 10
                },
                "connectorType": "REST",
                "id": "efca7eeb-96f6-4761-93cd-597bc6a5789f",
                "instanceCreated": true
            }
        ],
        "filter": {
            "eventIds": [
                "NETWORK-NON-FABRIC_WIRED-1-200"
            ],
            "others": []
        },
    ]   

Notification - Webhook API Schema and Payload

Event notification to webhook API endpoints will be the same, whether configured using the GUI or the Intent API. When/if the subscribed event occurs, your Catalyst Center will POST (or PUT, based on configuration) a notification message to the configured webhook API endpoint. The software at that endpoint is expected to parse and act on the received information and to return a status of 200 for correct delivery.

The example below shows sample values as delivered via POST to the configured URL:

Headers
    connection	close
    x-forwarded-for	173.36.240.173
    user-agent	okhttp/3.9.0
    accept-encoding	gzip
    host	webhook.site
    content-length	1019
    content-type	application/json; charset=utf-8

With payload body:

{
  "version": null,
  "instanceId": "ce7e8ade-bca0-4d89-9104-06dcc801c97b",
  "eventId": "NETWORK-NON-FABRIC_WIRED-1-200",
  "namespace": "ASSURANCE",
  "name": null,
  "description": null,
  "type": "NETWORK",
  "category": "ALERT",
  "domain": "Connectivity",
  "subDomain": "Non-Fabric Wired",
  "severity": 1,
  "source": "ndp",
  "timestamp": 1573152588740,
  "tags": null,
  "details": {
    "Type": "Network Device",
    "Assurance Issue Details": 
        "This network device CAMPUS-Dist2.cisco.com is unreachable from controller.
         The device role is DISTRIBUTION",
    "Assurance Issue Priority": "P1",
    "Device": "212.1.20.2",
    "Assurance Issue Name": "Network Device 212.1.20.2 Is Unreachable From Controller",
    "Assurance Issue Category": "Availability",
    "Assurance Issue Status": "active"
  },
  "ciscoDnaEventLink": 
        "https://172.28.97.216/dna/assurance/issueDetails?issueId=ce7e8ade-bca0-4d89-9104-06dcc801c97b",
  "note": 
        "To programmatically get more info see here -
         https://<ip-address>/dna/platform/app/consumer-portal/developer-toolkit/apis?apiId=8684-39bb-4e89-a6e4",
  "tntId": "",
  "context": null,
  "tenantId": ""
}

Synchronous Event Occurrence Information Queries

While a key purpose of the Event Management API methods is to support asynchronous notification to webhooks via API, users can also obtain event occurrence information by making a synchronous Intent API query. This is supported by the two 'Event-Series' methods. The key use of these methods is to provide a way to obtain information on past events occurrence such as when a webhook notification endpoint was unreachable or unavailable. A second use is to obtain additional information about an event occurrence. as the Event-Series GET response structure contains information not found in the initial notification POST or the Issue Enrichment API response.

GET Event-Series Count

The Event-Series Count query returns the number of notifications or attempted notifications, that have been issued, limited by filter criteria. Filters can be specified for eventIds, time range (start and end), type, severity, etc. Start and end times specified in Unix Epoch millisecond format.

In the example below, the filters are set to look for any Event occurrences in a time range of 1 second and in the "Connectivity" domain.
The count response is '1' indicating a single 'Connectivity' domain notification occurred in that one-second interval.

GET Event-Series List

We follow up with a query for the actual notification that occurred.

The complete response is shown below. It is similar to the webhook notification POST payload but contains additional details.

[   {
        "version": "1.0.0",
        "instanceId": "1dd772a7-c550-4cba-9c80-d8777f8c8a45",
        "eventId": "NETWORK-NON-FABRIC_WIRED-1-200",
        "namespace": "ASSURANCE",
        "name": null,
        "description": null,
        "type": "NETWORK",
        "category": "ALERT",
        "domain": "Connectivity",
        "subDomain": "Non-Fabric Wired",
        "severity": 1,
        "source": "ndp",
        "timestamp": 1573864788750,
        "tags": null,
        "details": {
            "managementIpAddr": "212.1.20.2",
            "fabricOrDeviceRole": "DISTRIBUTION",
            "_name": "switch_unreachable",
            "_entity_type": "NetworkDevice",
            "eventSource": "Network Device",
            "_key": "NetworkDevice:212.1.20.2",
            "type": "Issue",
            "floorId": "",
            "instanceId": "1dd772a7-c550-4cba-9c80-d8777f8c8a45",
            "areaName": "Global/US-Demo",
            "__type": "assurance_triggers",
            "scope": "global",
            "_primary_key": "NetworkDevice:212.1.20.2",
            "eventTime": 1573864788558,
            "tenantid": "5bde9f95041e6f004dcc24e6",
            "floorName": "",
            "siteType": "building",
            "severity": "HIGH",
            "deviceType": "Cisco Catalyst 4507R plus E Switch",
            "deviceUuid": "00a763ae-5dd9-462f-9abe-e1eb5c5e263f",
            "deviceRole": "DISTRIBUTION",
            "_suppression": "3600",
            "deviceOS": "03.04.00.SG",
            "entityType": "network_device",
            "nwDeviceName": "CAMPUS-Dist2.cisco.com",
            "entityId": "212.1.20.2",
            "eventUniqueId": "212.1.20.2",
            "deviceFamily": "Switches and Hubs",
            "priority": "P1",
            "_sink_version": "1.0.0",
            "buildingId": "816c27f9-be84-4017-b9b6-7b40db2252ae",
            "buildingName": "Global/US-Demo/Area1/Area1-BLDG2",
            "areaId": "0018dccf-573f-4f85-b783-6090866f6fb4",
            "siteHierarchy": "Global/US-Demo/Area1/Area1-BLDG2",
            "_appId": "assurance_issue_triggers",
            "deviceModel": "FOX1525G5S1",
            "category": "Availability",
            "status": "active"
        },
        "additionalDetails": {},
        "ciscoDnaEventLink": null,
        "note": null,
        "tntId": "5bde9f95041e6f004dcc24e6",
        "context": null,
        "tenantId": "SYS0"
    }
]

Intent API GET Issue Enrichment Method

The GET Issue Enrichment method is also be used to provide for additional information on an Event occurrence. It contains two elements of information not included in either the webhook API Notification payload or the Event-Series response. These are a list of "suggestedActions" that can be taken to address the issue and a list of zero or more 'impactedHosts'.
The query request takes two parameters:

• entity_value: Use the value of 'instanceId' as delivered in the notification API payload or as found in the Notification (Event-Series) response for the Event occurrence of interest. This value is a UUID and is also returned in the response payload as the "issueId".

• entity_type: use literal "issue_id".

For this example we'll use command line CURL. A sample CURL Issue Enrichment Details GET request is shown below followed by the corresponding response:

//'x-auth-token': 'x-auth-token-value' 
//'content-type': 'application/json' 
 curl --request GET \
  --url https://172.28.97.216/dna/intent/api/v1/issue-enrichment-details \
  --header 'entity_type: "issue_id"\
  --header 'entity_value: "ce7e8ade-bca0-4d89-9104-06dcc801c97b"

Response:

    "issueDetails": {
        "issue": [
            {
                "issueId": "ce7e8ade-bca0-4d89-9104-06dcc801c97b",
                "issueSource": "Cisco DNA",
                "issueCategory": "Availability",
                "issueName": "switch_unreachable",
                "issueDescription": 
                    "This network device CAMPUS-Dist2.cisco.com is unreachable from Cisco DNA Center. The device role is DISTRIBUTION.",
                "issueEntity": "network_device",
                "issueEntityValue": "212.1.20.2",
                "issueSeverity": "HIGH",
                "issuePriority": "",
                "issueSummary": 
                    "Network Device 212.1.20.2 is Unreachable From Cisco DNA Center",
                "issueTimestamp": 1573152588558,
                "suggestedActions": [
                    {
                        "message": "From the Cisco DNA Center, verify whether the last hop is reachable."
                    },
                    {
                        "message": "Verify that the physical port(s) on the network device associated with the network device discovery(IP) is UP."
                    },
                    {
                        "message": "Verify access to the device."
                    }
                ],
                "impactedHosts": []
            }
        ]
    }

Additional Resources

Cisco API

• Cisco Intent API Specification

Cisco Catalyst Center Administrator and User Guides

• Most guides are specific to a Cisco Catalyst release version. Use the guide corresponding to your Cisco Catalyst Center release version.*

• Cisco Catalyst Center End User Guides

• Cisco Catalyst Center Platform Guides

• Cisco Catalyst Center Administrative and High Availability Guides.

• Cisco Catalyst Center Appliance Installation Guides

• Release notes, licensing information, and other installation guides.

Cisco Developer Tools and Assistance

• Cisco Catalyst Center Platform: Hello World

• CiscoDevNet: DNAC-postman