The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This chapter describes the Event API:
■Handling Event Notifications On the Client Side
In your IoT FND NB API client application, use this IoT FND server URL to access the Event API WSDL:
This call searches for events based on device type, event name, event time, and event severity.
|
|
|
---|---|---|
Use the parameters in Query Parameters and the options listed in eventName Query Options in the query.
|
|
|
|
---|---|---|---|
Options are listed in eventName Query Options. |
|||
|
|
|
---|---|---|
Subscription ID used by the listener to identify the subscription response origin. |
||
searchEvents SOAP XML Request Format
This call streams a set of events to the API listener, based on the query. Event subscriptions are based on device type, event name, or severity. Listener registers the URL and specifies the push window. After every configured eventPushWindowSec event push window, all new events received in this window are delivered to the registered URL. Subscription-based events notification uses the same query language as searchEvents, except that the eventTime attribute-based queries cannot be subscribed to and return unsuccessful subscription errors.
|
|
|
---|---|---|
The address of the WSDL file–as implemented by your client–that receives event notifications from the IoT FND NB API. For more information, see Handling Event Notifications On the Client Side. http:// <server_address> : <port number> / <path><api> ?wsdl http://localhost:8445/event?wsdl soapEndPointUrl must point to the WSDL document that describes the listener application receiving the events. Ensure that the target namespace and service name parameters in the Web Services Description Language (WDSL) document conform to these default values: Note: Release 2.1 and later installations support https for soapEndPointUrl. Functionality in IoT FND 1.1.3 and later installations Some applications cannot set the default values for these parameters when generating the WSDL file. If this is the case, in IoT FND 1.1.3 and later installations you can set the following properties in the server/cgms/conf/cgms.properties file to match the values in the generated WSDL document: The target namespace and service name parameters must match those specified in the cgms.properties file. If they are not specified in the cgms.properties file, they must match the default values. Note: Only one set of these values is allowed in the cgms.properties file. If there are multiple subscribers, they must use the target namespace and service name parameter values specified in all WSDL documents pointed to in the soapEndPointUrl of the subscriptions. |
||
Note: The query language eventTime field cannot be inside the subscription. |
||
The event push window time, in seconds. The query executes after x seconds, and the results are pushed to the listener endpoint specified in the soapEndPointUrl WSDL file. |
|
|
|
---|---|---|
The QueryResult Status field indicates if the subscription succeeded or failed.
subscribeForEvents SOAP XML Request Format
This call unsubscribes the defined listener event query.
|
|
|
---|---|---|
The QueryResult Status field indicates if the subscription succeeded or failed.
unSubscribeForEvents SOAP XML Request Format
This call is similar to subscribeForEvents, except that it is for outage and restoration events. Up to 10 subscribers (listeners) at a time can register for these events.
|
|
|
---|---|---|
Address of the WSDL, implemented by your client, that receives outage notifications from the IoT FND NB API. For more information, see Handling Event Notifications On the Client Side. http:// <server_address> : <port number> / <path><api> ?wsdl http://localhost:8445/outage?wsdl Note: Release 2.1 and later installations support https for soapEndPointUrl. |
To configure the amount of time, in seconds, after which IoT FND pushes batches of outage events and Restoration Events to all subscribers, set the value of the event-Outage-push-sec parameter in the /opt/cgms/conf/cgms.properties file. For example, to set event-Outage-push-sec to 30, add this line to the file:
When IoT FND pushes outage events to subscribers, only subscribers that are up receive the events. The subscribers that are down (they do not respond) do not receive these events even after they come back online, but they receive the next outage event push.
For a very fast outage event push, set event-Outage-push-sec to a value as low as 1 second. If you set the push value to 1 second, IoT FND executes a job to find and push new events in the queue.
|
|
|
---|---|---|
Subscription ID which can be used by the listener to identify for which subscription they are getting the response from. |
The QueryResult Status field indicates if the subscription succeeded or failed.
subscribeForCgmeshOutage SOAP XML Request Format
This call unsubscribes the defined listener.
unSubscribeForCgmeshOutage Parameters describes the parameters in the request.
|
|
|
---|---|---|
The QueryResult Status field indicates if the subscription succeeded or failed.
unSubscribeForCgmeshOutage SOAP XML Request Format
When subscribing for an event type, your IoT FND NB API client must implement a Web Service that implements the WSDL for handling event notifications sent by the IoT FND NB API. The WSDL you must provide the receiveEvents() method, which the IoT FND NB API uses to send event notifications to your client.
In Event Notification Handling, the IoT FND NB API client implements the Outage WSDL. When the client subscribes for outage events, IoT FND uses the IoT FND NB API to call the method receiveEvents() on the IoT FND NB API client.
Figure 1 Event Notification Handling
This is the Event XML that your client must implement to receive outage notifications from IoT FND.
Your client must implement this WSDL:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://pushevent.nbapi.cgms.cisco.com/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" name="eventPush"
targetNamespace="http://pushevent.nbapi.cgms.cisco.com/">
<xsd:schema targetNamespace="http://pushevent.nbapi.cgms.cisco.com/">
<xsd:element name="receiveEvents" type="tns:receiveEvents" />
<xsd:complexType name="receiveEvents">
<xsd:element minOccurs="0" name="eventQueryResult"
type="tns:eventQueryResult" />
<xsd:complexType name="eventQueryResult">
<xsd:extension base="tns:queryResult">
<xsd:element maxOccurs="unbounded" minOccurs="0"
name="events" nillable="true" type="tns:eventDetail" />
<xsd:element name="subscriptionId" type="xsd:long" />
<xsd:complexType abstract="true" name="queryResult">
<xsd:element minOccurs="0" name="queryId" type="xsd:string" />
<xsd:element minOccurs="0" name="queryStatus" type="xsd:string" />
<xsd:complexType name="eventDetail">
<xsd:element minOccurs="0" name="eid" type="xsd:string" />
<xsd:element minOccurs="0" name="eventMessage" type="xsd:string" />
<xsd:element minOccurs="0" name="eventSeverity" type="xsd:string" />
<xsd:element minOccurs="0" name="eventTime" type="xsd:long" />
<xsd:element minOccurs="0" name="eventTypeName" type="xsd:string" />
<xsd:element minOccurs="0" name="meterId" type="xsd:string" />
<wsdl:message name="receiveEvents">
<wsdl:part element="tns:receiveEvents" name="receiveEvents" />
<wsdl:portType name="EventPushService">
<wsdl:operation name="receiveEvents">
<wsdl:input message="tns:receiveEvents" />
<wsdl:binding name="EventPushServiceBinding" type="tns:EventPushService">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http" />
<wsdl:operation name="receiveEvents">
<soap:operation soapAction="http://pushevent.nbapi.cgms.cisco.com/receiveEvents" />
<wsdl:service name="EventPushService">
<wsdl:port binding="tns:EventPushServiceBinding" name="EventPushService">
Push mechanisms work only when the NMS server has successfully completed the subscription, as defined in the subscribeForEvents and subscribeForCgmeshOutage API methods.
A successful subscription leads to generation of the Subscription ID that is sent to the subscriber. The subscriber uses the Subscription ID to track the event push.
IoT FND runs a Scheduled Job every x seconds. Seconds are configurable during the subscription by using the event-Outage-push-sec global parameter defined in the /opt/cgms/conf/cgms.properties file. After every x seconds, IoT FND generates an EventList and pushes it to the subscribers defined in the soapEndPointUrl.
The web service to implement on the NMS side is:
The QueryResult Status field indicates if the subscription succeeded or failed. EventQueryResult Response describes the parameters in the response.
|
|
|
---|---|---|
Subscription ID used by the listener to identify which subscription the response is from. |
||
EventDetail Response describes the parameters in the EventDetail results.
This is an example of the XML content that the subscriber receives:
The subscriptionId XML element (<subscriptionId>2</subscriptionId>) tells the receiver that this push is for the subscription ID equal to 2.