Cisco Prime Central for Hosted Collaboration Solution 9.2.1 Programmer Guide
Chapter 2: Understanding Web Service Interface
Downloads: This chapterpdf (PDF - 247.0KB) The complete bookPDF (PDF - 923.0KB) | Feedback

Understanding the Web Service Interfaces

Table Of Contents

Understanding the Web Service Interfaces

Interfaces

Data

Filtering

Rules for Writing Filters


Understanding the Web Service Interfaces


Using Prime Central for HCS, you can view the events in a single dashboard that originates from the domain managers.

This chapter contains the following sections:

Interfaces

Data

Filtering

Interfaces

Prime Central for HCS supports two northbound interfaces (NBI). They are:

SNMP Notifications—Prime Central for HCS supports SNMP Trap Notifications. SNMP listeners are added, updated, or removed by WebServices API.

WebServices API—Prime Central for HCS supports the following WebServices APIs:

authenticate—authenticate Response

getActiveEventCount—getActiveEventCount Response

getActiveEvents—getActiveEvents Response

getArchivedEventsCount—getArchivedEventsCount Response

getArchivedEvents—getArchivedEvents Response

getEvent—getEvent Response

getOperationalData—getOperationalData Response

subscribe—subscribe Response

unSubscribe—unSubscribe Response

Data

Incoming events are alarms raised by the underlying domain managers (such as Cisco Unified Operations Manager (CUOM), UCS Manager) that indicates the status of the managed devices. Prime Central for HCS supports various levels of processing for these incoming events and they listed below:

Normalized-only events—Events that Prime Central for HCS receives and normalizes. These events are not enriched further. It passes on the events directly to a northbound system without additional processing. These events are marked with EventTypeID=default.

Enriched events—After normalization, some events are enriched with additional information. For example, CUOM events are enriched with the CustomerName, the VM Name in which the UC application is running, and others. Some of the enriched events are used to determine its impact on customer services by overlaying them on the service impact tree.

Root-cause events—Raw or synthetic events that are the root-cause of the failure.

Symptomatic events—Raw or synthetic events that are part of event correlation but not the root-cause of the failure.

Synthetic Events—These are events generated internally to indicate a category of events. For example, all Service Down events on a CUCM node, which indicate that services running on the CUCM node are down, are grouped under the Synthetic event named OM_CUCM_Processed. Synthetic events that participate in the correlation tree are used for root cause analysis.

Service-impact events—Service-impact events describe the state of services; this is an event generated to notify the state of the top node in the service impact tree.

For more information on the enrichment level, see table Table 2-1. For more information on individual field names in an NBI event notification, see table Table 2-2.

When symptom and root-cause events arrive, it is possible that a symptom event is marked as a root-cause event until such time as the root-cause event arrives. After the real root-cause event arrives, the CauseType of the symptom event changes to symptom.

If you have set subscription filters based on CauseType, you will receive the symptom event as a root-cause event. However, this will later be updated with the CauseType Symptom.

Table 2-1 Level of Event Enrichment Based on Various Parameters 

Field Name
Normalized-Only Events
Enriched-Only Events
Root-Cause Events
Symptomatic Events
Service Impact Events

EventIdentifier

Yes

Yes

Yes

Yes

Yes

EventName

Yes

(only for CUOM, UCSM, Infrastructure Monitoring)

Yes
(only for CUOM, UCSM, Infrastructure Monitoring)

Yes

(same as EventType ID)

Yes

(same as EventType ID)

Summary

Yes

Yes

Yes

Yes

Yes

ComponentId

Yes

(only for CUOM, UCSM, Infrastructure Monitoring)

Yes

(only for CUOM, UCSM, Infrastructure Monitoring)

Yes

(only vCenter and UCSM Events)

Yes

(only vCenter and UCSM Events)

DeviceId

Yes

Yes

Yes

Yes

DomainManagerID

Yes

Yes

Yes

Yes

Customer

Yes

(Only OM & Infrastructure Monitoring VM events)

Yes

(Only OM & Infrastructure Monitoring VM events)

Yes

(Only OM & Infrastructure Monitoring VM events)

Yes

CustomerExtName

Yes

(Only OM & Infrastructure MonitoringVM events)

Yes

(Only OM & Infrastructure MonitoringVM events)

Yes

(Only OM & Infrastructure Monitoring VM events)

Yes

CauseType

Yes (set to Unknown)

Yes (set to Unknown)

Yes (set to Rootcause)

Yes (set to Symptom)

ParentEventID

Yes

Yes

Severity

Yes

Yes

Yes

Yes

Yes

OriginalSeverity

Yes

Yes

EventTypeId

Yes

Yes

Yes

ProblemeventID

Yes

Yes

Yes

Yes

Yes

ServiceName (for service events only)

Yes

ServiceImpactType (for service events only)

Yes

OperationalDataPointer

Yes

(only for CUOM, UCSM, Infrastructure Monitoring)

Yes
(only for CUOM, UCSM, Infrastructure Monitoring)

Dashboard URL

Yes

Yes

Yes

Yes

Yes

Count

Yes

Yes

Last Occurrence

Yes

Yes

Yes

Yes

Yes

Event Status

Yes

Yes

Yes

Yes

 

This section explains the formats of the incoming SNMP v2C Trap and description of the associated variable bindings. This table also indicates the fields or variable bindings that can be used to filter the incoming data.

Table 2-2 NBI Event Format 

Field Name
Filterable
Field Description
Field Type
Field Value
Varbind O ID

EventName

Yes

Name of the event

OctetString

Synthetic events: HCM defined EventName (similar to EventTypeID)

UCSM events: text representation of cucsFaultCode enum

CUOM events: EventName

1.3.6.1.4.1.1279.1

Summary

No

Brief description of the event

OctetString

Synthetic events: HCS defined event summary

CUOM events: AlarmDescription

UCSM events: cencucsFaultDescription

1.3.6.1.4.1.1279.2

ComponentId

Yes

Name/identifier of the component within device that event is raised for (For example, UCS blade)

OctetString

Synthetic events: take below fields from original domain manger event

CUOM events:cenAlarmManagedObjectClass

UCSM events: cucsFaultAffectedObjectDn

1.3.6.1.4.1.1279.3

DeviceId

Yes

Hostname or IP of device that originated event (For example, CUCM, Router, etc.)

OctetString

1.3.6.1.4.1.1279.4

Domain ManagerID

Yes

IP address of domain manager that sent event to Prime Central for HCS (For example, CUOM, UCSM, etc.)

OctetString

1.3.6.1.4.1.1279.5

Customer

Yes

Customer Name

OctetString

1.3.6.1.4.1.1279.6

Customer ExtName

Yes

Customer Name used in MSP external CMDBs (stored in HCS CDM)

OctetString

1.3.6.1.4.1.1279.7

CauseType

Yes

Flag indicating whether event is the root cause or symptomatic event

0—Unknown

1—Root cause

2—Symptom number True for events identified as root-cause and marked only after root cause is finalized, that is after the RCA timer expires. False for others.

Gauge32

1.3.6.1.4.1.1279.8

ParentEvent ID

No

EventID pointing to parent event in correlation tree - can be used by NB system to reconstruct Prime Central for HCS event correlation tree for this event

OctetString

1.3.6.1.4.1.1279.9

Severity

Yes

Event severity assigned by Prime Central for HCS:

0—Clear

1—Indeterminate

2—Warning

3—Minor

4—Major

5—Critical

Gauge32

For cleared events severity = 0;

For active events, see Prime Central for HCS and Domain Manager Severity Mapping

1.3.6.1.4.1.1279.10

Original Severity

No

Original event severity assigned by domain manager.

OctetString

1.3.6.1.4.1.1279.11

EventTypeId

No

ID used to group domain manager events with the similar impact on component state for common Prime Central for HCS processing. For example, UCS_Blade_Availability includes all events causing blade failure.

OctetString

See EventTypeID Mapping.

1.3.6.1.4.1.1279.12

ProblemeventID

No

Used for clearing event. Refers to previous problem event which it clears.

OctetString

EventID of the event that is being cleared

1.3.6.1.4.1.1279.13

ServiceName (for service events only)

Yes

Name of Prime Central for HCS service that event is raised for (For example, Customer Voice).

OctetString

Name of top node of service impact tree (for example, Customer Voice Service).

1.3.6.1.4.1.1279.14

ServiceImpactType (for service events only)

Yes

Service state; state of the service with ServiceName.

OctetString

State of the top node of instance of service impact tree (for example, state of Customer Voice Service for customer X); Values can be: UP, MARGINAL or DOWN

1.3.6.1.4.1.1279.15

OperationalDataPointer (for RC events only)

No

Pointer to the knowledge base/reference guides with next steps information

OctetString

URL to specific event as specified in domain manager event reference guide

1.3.6.1.4.1.1279.16

Count

No

Number of times this event has occured.

Gauge32

1.3.6.1.4.1.1279.17

Type

Yes

1—More Severe

2—Less Severe

3—Information

Gauge32

1.3.6.1.4.1.1279.18

Last Occurrence

No

Timestamp indicating when the event last occurred. The value is represented in seconds since epoch.

Gauge32

1.3.6.1.4.1.1279.19

PrimeGuiUrl

No

Event URL.

OctetString

1.3.6.1.4.1.1279.20

EventIdentifier

Yes

Unique ID for each event.

OctetString

1.3.6.1.4.1.1279.21

ContainerId

Yes

Synthetic Event Identifier for Raw events.

OctetString

1.3.6.1.4.1.1279.22

FirstOccurrence

No

Timestamp indicating when event first occurred. The value is represented in seconds since epoch.

Gauge32-

1.3.6.1.4.1.1279.23


The following table explains the mapping of severity between Prime Central for HCS and domain managers.

Table 2-3 Prime Central for HCS and Domain Manager Severity Mapping 

Prime Central for HCS Severity
CUOM Severity
UCSM Severity
DCSM-SAN Severity
DCNM-LAN Severity
Infrastructure Monitoring Severity

0—Clear, Green

N/A

0—Clear

1—Indeterminate, Purple

N/A

1—Info

Debugging

Debugging

Informational

2—Warning, Blue

Informational

3—Warning

Info, Notification

Info, Notification

Harmless

3—Minor, Yellow

Warning

4—Minor

Warning

Warning

Warning

4—Major, Orange

N/A

5—Major

Alert, Emergencies

Alert, Emergencies

5—Critical, Red

Critical

6—Critical

Error, Critical

Error, Critical

Critical


Filtering

Using the filtering arguments available in the Prime Central for HCS Northbound API you can retrieve event data based on your requirements. For information on examples of usage of whereclause, see Examples of Usage of whereclause.

To see if the data is filterable, see table Table 2-2. You can set filters based on the parameters outlined in the table.

Rules for Writing Filters

There are three categories of filters associated with the NBI. They are:

Gateway filter—Used in the subscribe API of the NBI. Gateway filter defines which of the events should be forwarded to the destination.

Active event retrieval filter—Used in the getActiveEvents and getActiveEventCount API of the NBI. This filter defines which of the events should be retrieved from the Active event database.

Archive event retrieval filter—Used in the getArchivedEvents and getActivedEventCount API of the NBI. This filter defines which of the events should be retrieved from the Archived event database.

The following restrictions apply:

Filters follow the format of a SQL where clause. For more information, see chapter WSDL Specifications.

You can specify only those columns that are marked as filterable and they are listed in Table 2-2.


Note The Fieldnames are case-sensitive. Specify exactly as mentioned in the Table 2-2.


Review the Field type to understand if a column is of type Number or String. The filter expression syntax is different for these two types of variables.

It may also be necessary to review the expected set of values for the columns that are of type Number. For example, for active events, you must specify EventStatus=1. For symptomatic events, you must specify CauseType=2.

Do not use Ampersand (&) to filter data.

The following rules apply when specifying where clause conditions:

Where clause can include logical operators such as AND and OR.

Where clause can include standard comparison operators such as <, >, <=, >=, =, !=, <>

Oracle-specific conditional clauses is null or not null are not supported.

Use column != ' ' to get expected output.

IN clause is supported.

LIKE clause is supported with an exception that Percentage (%) and Underscore (_) are treated as literals.

String (VARCHAR) values within WHERE condition must be specified within single quotes (for example, DeviceId='CUCM-1').

Numbers within WHERE condition must be specified without any quotes (for example, Severity=5)