Programmer's Guide for Cisco Prime Central for Hosted Collaboration Solution, 1.0.1
Chapter 2: Understanding Web Service Interface
Downloads: This chapterpdf (PDF - 146.0KB) The complete bookPDF (PDF - 1.18MB) | Feedback

Understanding Web Service Interface

Table Of Contents

Understanding Web Service Interface

Interfaces

Data

Filtering

Rules for Writing Filters


Understanding Web Service Interface


Using Prime Central for HCS, you can view the events in a single normalized northbound interface. Using the different kinds of interfaces, you will be able to filter the data that originates from the domain managers. This chapter contains the following sections:

Interfaces

Data

Filtering

Interfaces

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

SNMP Notifications—Prime Central for HCS supports SNMP Trap Notifications. NBI listeners are added/updated/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 CUOM, UCS Manager) the indicate the health of the managed devices. Prime Central for HCS supports various levels of processing for these incoming events. Shown below are the various levels of processing:

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 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—Synthetic events that were determined to be root-cause of the failure.

Symptomatic events—Synthetic events that were part of event correlation but were determined not to be 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 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 "Level of Event Enrichment Based on Various Parameters". For more information on individual field names contained in an NBI event notification, see table "NBI Event Format".

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)

Summary

Yes

Yes

Yes

Yes

Yes

ComponentId

Yes

(only for CUOM, UCSM, Infrastructure Monitoring)

Yes

(only for CUOM, UCSM, Infrastructure Monitoring)

DeviceId

Yes

Yes

Yes

Yes

DomainManagerID

Yes

Yes

No

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)


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 Oid

EventName

No

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

DomainManagerID

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

CustomerExtName

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

ParentEventID

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)

No

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)

No

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

EventStatus

Yes

0—Type not set

1—Problem

2—Resolution

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 Prime Central for HCS Northbound API, you can retrieve event data based on your requirement. For information on examples of usage of whereclause, see Examples of Usage of whereclause.

To see if the data is filterable, see table "NBI Event Format". You can set filters based on the parameters outlined in the table.

Rules for Writing Filters

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

Gateway filter—Used to subscribe API of 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 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 NBI. This filter defines which of the events should be retrieved from the Archived event database.

The following restrictions apply:

Filters will follow the format of SQL Where Clause. For more information, see chapter WSDL Specifications.

You can specify only those columns which are marked as filterable. Filter clause should then use the corresponding name as specified in Field Name column of "NBI Event Format" to be used in NBI Filter.


Note The name is case sensitive. Specify exactly as mentioned in the table.


Review the Field type to understand if a column is of type Number or of type String. The filter expression syntax will be 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.

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 clause "is null" or "not null" are not supported.

(Use column != ' ' instead to get expected output)

IN clause is supported

LIKE clause is supported with an exception that % and _ characters will be 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)