Programmer's Guide for Cisco Prime Central for Hosted Collaboration Solution, 1.0.1
Chapter 3: WSDL Specifications
Downloads: This chapterpdf (PDF - 127.0KB) The complete bookPDF (PDF - 1.18MB) | Feedback

WSDL Specifications

Table Of Contents

WSDL Specifications

WSDLs in Prime Central for HCS

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

Exception Handing

Examples of Usage of whereclause

Example of Java language Binding File


WSDL Specifications


You can develop web-service clients using the WSDLs explained below. The WSDL is available at https://<prime-central-ip-address>:9090/EventManagement?wsdl.

This chapter contains the following sections.

WSDLs in Prime Central for HCS

Exception Handing

Examples of Usage of whereclause

Example of Java language Binding File

WSDLs in Prime Central for HCS

This section explains the WSDLs that you can leverage. The whereclause is explained in "NBI Event Format". For examples of whereclause, see Examples of Usage of whereclause.

The following operations are applicable for Prime Central for HCS:

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

authenticate—authenticate Response

This WSDL authenticates users against Prime Central for HCS. As response, it provides session token to be used for subsequent requests.

The following table describes the arguments used in the WSDL:

Argument
Description

username

Username for Prime Central for HCS

password

Password for the above user.


getActiveEventCount—getActiveEventCount Response

Returns the count of rows that contain active events. The response is a number that represents the number of active events.

The following table describes the arguments used in the WSDL:

Argument
Description

whereclause

Filter in SQL format.

sessionToken

Session ID obtained using authenticate.


The following table provides the description of return values:

Return Value
Description

NumberOfActiveEvents

The number of events currently active (uncleared) in the system.


getActiveEvents—getActiveEvents Response

This operation returns the available active events. The response to this request is a list of all active events.
The following table describes the arguments used in the request:

Argument
Description

whereClause

Filter in SQL format.

sessionToken

Session ID obtained using authenticate.


getArchivedEventsCount—getArchivedEventsCount Response

This request gets the number of archived events from archive database. The response is a number that represents the number of archived events.

The following table describes the arguments used in the WSDL

:

Argument
Description

whereclause

Filter in SQL format.

sessionToken

Session ID obtained using authenticate.


The following table provides the description of return values:

Return Value
Description

ArchivedEventsCount

Count of the number of archived events.


getArchivedEvents—getArchivedEvents Response

The request can be used to retrieve archived events from the archive database. The response is a list of all archived events in the archive database.

The following table describes the arguments used in the WSDL:

Argument
Description

whereclause

Filter in SQL format.

sessionToken

Session ID obtained using authenticate.


The following table provides the description of return values:

Return Value
Description

ArchivedEventsList

List of archived events.


getEvent—getEvent Response

This requests gets the active events present in the database. The response provides active or archived events present in the database.

The following table describes the arguments used in the WSDL:

Argument
Description

EventId

EventIdentifier of the event.

sessionToken

Session ID obtained using authenticate.


The following table provides the description of return values:

Return Value
Description

Event

The event that matches the specified EventId.


getOperationalData—getOperationalData Response

This request serves the next steps URL or HTML fragment. The response is a URL to a page that contains next steps or a HTML fragment that contains next steps.

The following table describes the arguments used in the WSDL:

Argument
Description

eventName

EventName of an event. For example, For example, PerformancePollingStopped,SysLogIdentifier

sessionToken

Session ID obtained using authenticate.


subscribe—subscribe Response

This request lets you subscribe to receive SNMP traps for the events. The response returns SubscriptionID. This SubscriptionID must be used to unsubscribe. For example, the SubscriptionID can be Customer_99.

The following table describes the arguments used in the WSDL:

Argument
Description

snmpgatewayAddr

IP address of the device to which the SNMP traps have to be sent.

snmpGatewayPort

Port number to which the SNMP traps have to be sent.

whereClause

Filter in SQL format.

sessionToken

Session ID obtained by using authenticate.


unSubscribe—unSubscribe Response

Performs the request to unsubscribe a previously subscribed request.

The following table describes the arguments used in the WSDL:

Argument
Description

SubscriptionID

SubscriptionID obtained using a subscribe request.

sessionToken

Session ID obtained using authenticate.


Exception Handing

Any error encountered by the NBI component is returned to the NBI client through a generic EventManagementException object. This includes an error message describing the specific problem that might have occurred. For example:

Error Message    The requested operation could not be completed due to a system 
error:Not a valid session, Please re-authenticate. 

Explanation    You specified an invalid sessionToken in the API invocation, and an EventManagementException object is returned.

Error Message    Error Message: The requested operation could not be completed due to a system error:Incorrect result size: expected 1, actual 0. 

Explanation    You attempted to unsubscribe with an incorrect customer ID.

Recommended Action    Specify the correct customer ID.

Examples of Usage of whereclause

This section presents some examples of the usage of whereclause. For more information on the usage, see "NBI Event Format". You can filter based on various parameters, and some of them are outlined below:

Specifying filter for GetEvents

Verify method getActiveEvents using filter whereClause = DeviceId (example, send only events originated by specific CUCM)

		<whereClause>Node='CUCM-1'</whereClause>  

Verify method getActiveEvents using filter whereClause = Severity (example, send only critical Prime Central for HCS events)

		<whereClause>Severity=5</whereClause> 
 
   

Verify method getActiveEvents using filter whereClause = Event status (cleared) (example, send only cleared events)

		<whereClause>type=2</whereClause>  
 
   

Verify method getActiveEvents using filter whereClause = Event status (active) (example, send only active events)

		<whereClause>type=1</whereClause>  
 
   

Specifying filter for Subscription

Verify method subscribe snmp traps with snmpgatewayAddr,snmpGatewayPort, for root-cause events

		<whereClause>CauseType=1</whereClause>  

Verify method subscribe snmp traps with snmpgatewayAddr,snmpGatewayPort, for Symptomatic events

			<whereClause>CauseType=2</whereClause>  

Example of Java language Binding File

The following is an example of a Java language binding generated for the WSDLs above. You have the option of using a language of your choice to create VarBinds. You can create the Java source using the SOAP engines CXF or Muse/Axis2. For more information on filtering events, see Filtering.

 
   
package com.cisco.hcm.fronthandler;
 
   
import java.util.List;
 
   
import javax.jws.WebParam;
import javax.jws.WebService;
import javax.xml.bind.annotation.XmlElement;
 
   
import com.cisco.hcm.events.Event;
import com.cisco.hcm.utils.EventManagementException;
 
   
@WebService(name = "EventManagement", targetNamespace = 
"http://fronthandler.hcm.cisco.com/")
public interface EventManagement {
 
   
	/**
	 * 
	 * @param whereClause
	 * @param sessionToken
	 * @return
	 * @throws EventManagementException
	 * Returns the active events in Omnibus objectserver
	 */
	public List<Event> 
getActiveEvents(@XmlElement(required=true)@WebParam(name="whereClause")String whereClause 
,@XmlElement(required=true)@WebParam(name="sessionToken")String sessionToken) throws 
EventManagementException;
 
   
	/**
	 * 
	 * @param whereClause
	 * @param sessionToken
	 * @return
	 * @throws EventManagementException
	 * Returns the Archived events
	 */
	public List<Event> 
getArchivedEvents(@XmlElement(required=true)@WebParam(name="whereClause")String 
whereClause , @XmlElement(required=true)@WebParam(name="sessionToken")String sessionToken) 
throws EventManagementException;
 
   
	/**
	 * 
	 * @param eventId
	 * @param sessionToken
	 * @return
	 * @throws EventManagementException
	 */
	public Event getEvent(@XmlElement(required=true)@WebParam(name="eventId")String 
eventId , @XmlElement(required=true)@WebParam(name="sessionToken")String sessionToken) 
throws EventManagementException;
 
   
	/**
	 * 
	 * @param whereClause
	 * @param sessionToken
	 * @return
	 * @throws EventManagementException
	 * Return Count of the rows based on filter
	 */
	public int 
getActiveEventCount(@XmlElement(required=true)@WebParam(name="whereClause")String 
whereClause , @XmlElement(required=true)@WebParam(name="sessionToken")String sessionToken) 
throws EventManagementException;
 
   
	/**
	 * 
	 * @param whereClause
	 * @param sessionToken
	 * @return
	 * @throws EventManagementException
	 * Return Count of the rows based on filter
	 */
	public int 
getArchivedEventCount(@XmlElement(required=true)@WebParam(name="whereClause")String 
whereClause , @XmlElement(required=true)@WebParam(name="sessionToken")String sessionToken) 
throws EventManagementException;
 
   
	/**
	 * 
	 * @param snmpgatewayAddr
	 * @param snmpGatewayPort
	 * @param whereClause
	 * @param sessionToken
	 * @return
	 * @throws EventManagementException
	 * Serve the Subscribe request
	 */
	public String 
subscribe(@XmlElement(required=true)@WebParam(name="snmpgatewayAddr")String 
snmpgatewayAddr, @XmlElement(required=true)@WebParam(name="snmpGatewayPort")String 
snmpGatewayPort,
			@XmlElement(required=true)@WebParam(name="whereClause")String whereClause , 
@XmlElement(required=true)@WebParam(name="sessionToken")String sessionToken) throws 
EventManagementException;
 
   
	/**
	 * 
	 * @param customerToken
	 * @param sessionToken
	 * @return
	 * @throws EventManagementException
	 * Serve the Un-Subscribe request
	 */
	public String 
unSubscribe(@XmlElement(required=true)@WebParam(name="customerToken")String customerToken 
, @XmlElement(required=true)@WebParam(name="sessionToken")String sessionToken) throws 
EventManagementException;
	
	/**
	 * 
	 * @param eventCode
	 * @param sessionToken
	 * @return
	 * @throws EventManagementException
	 * Serve the next steps request
	 */
	public String 
getOperationalData(@XmlElement(required=true)@WebParam(name="eventName")String eventCode , 
@XmlElement(required=true)@WebParam(name="sessionToken")String sessionToken) throws 
EventManagementException;
	
	/**
	 * 
	 * @param username
	 * @param password
	 * @return
	 * @throws EventManagementException
	 * Provides sessionToken to be used for other requests
	 */
	public String authenticate(@XmlElement(required=true)@WebParam(name="username")String 
username, @XmlElement(required=true)@WebParam(name="password")String password) throws 
EventManagementException;
 
   
}