Configuring Event Notifications

With the Cisco Prime Infrastructure, you can define conditions that cause the mobility services engine to send notifications to specific listeners. This chapter describes how to define events and event groups and how to view event notification summaries.


Note
The Cisco Mobility Services Engines, Synchronize Services, Synchronization History, High Availability, Context Aware Notifications, and MSAP pages from the Services tab is available only in the virtual domain in Release 7.3.101.0.

Information About Event Notifications

  • Event Group—Helps you organize event notifications
  • Event Definition—An event definition contains the condition that caused the event, the assets to which the event applies, and the event notification destination.
  • Event Notification—A mobility services engine sends event notifications to registered listeners over the following transport mechanisms.
    • Simple Object Access Protocol (SOAP)
    • Simple Mail Transfer Protocol (SMTP)
    • Simple Network Management Protocol (SNMP)
    • Syslog

Viewing Event Notification Summary

The mobility services engine sends event notifications and does not store them. However, if Prime Infrastructure is a destination of notification events, it stores the notifications it receives and groups them into the following seven categories:

  • Absence (Missing)—The MSE generates an absence event when an asset goes missing. In other words, the MSE cannot detect the asset in the WLAN for the specified time.
  • In/Out Area (Containment)—The MSE generates a containment event when an asset moves in or out of a designated area.

    Note

    You define a containment area (campus, building, or floor) using Monitor > Maps. You can define a coverage area using the Map Editor.

  • Movement from Marker (Movement/Distance)—The MSE generates a movement event when an asset is moved beyond a specified distance from a designated marker you define on a map.
  • Location Changes—The MSE generates location change events when a client station, asset tag, rogue client, or rogue access point changes its location.
  • Battery Level—The MSE generates battery level events for all tracked asset tags.
  • Emergency—The MSE generates an emergency event for a Cisco CX v.1-compliant asset tag when the panic button of the tag is triggered or the tag becomes detached, is tampered with, becomes inactive, or reports an unknown state. This information is reported and displayed only for Cisco CX v.1-compliant tags.
  • Chokepoint Notifications—The MSE generates an event when a tag is stimulated by a chokepoint. This information is reported and displayed only for Cisco CX v.1-compliant tags.

    Note

    All element events are summarized hourly and daily.


    Note

    The Track Group and events must be synchronized with a MSE.

Clearing Notifications

  • Missing (Absence)—Elements (clients, tags, rogue access points, or rogue clients) reappear.
  • In/Out Area (Containment)—Elements move back in to or out of the containment area.
  • Distance—Elements move back within the specified distance from a marker.
  • Location Changes—Clear state does not apply to this condition.
  • Battery Level—Tags are detected and operate with normal battery level.

Note

In Prime Infrastructure, the Notifications Summary page reflects whether notifications for cleared event conditions have been received.

Notification Message Formats

Notification Formats in Text

When you specify that notification be sent in text format, the mobility services engine uses a plain-text string to indicate the condition:

Tag 00:02:02:03:03:04 is in Floor <floorName>
Tag 00:02:02:03:03:04 is outside Floor <floorName>
Client 00:02:02:03:09:09 is in Area <areaName>
RogueClient 00:02:02:08:08:08 is outside Building <buildingName>
Tag 00:02:02:03:03:06 has moved 105 feet where the trigger distance was 90 feet.
Tag 00:02:02:03:03:20 missing for 14 mins, last seen <timestamp>.

Note

Cisco maintains the right to modify the text notification format without notice.


Note

XML is the recommended format for systems that need to parse or analyze notification contents.

Notification Formats in XML


Note

The XML format is part of a supported API. Cisco provides change notification as part of the Mobility Services Engine API program whenever the API is updated in the future.

Missing (Absence) Condition

Message format for element absence: 


<AbsenceTrackEvent
missingFor="<time in secs entity has been missing>"
lastSeen="time last seen"
trackDefn="<name of track definition>"
entityType="Mobile Station | Tag | Rogue AP | Rogue Client"
entityID="<mac address"/>

Message format for the Clear state: 


<AbsenceTrackEvent
state="clear"
trackDefn="<name of track definition>"
entityType="Mobile Station | Tag | Rogue AP | Rogue Client"
entityID="<mac address"/>

For example: 


<AbsenceTrackEvent state="set" missingFor="34" lastSeen="15:00:20 08 
Jun 2009" trackDefn="absenceDef1" entityType="Mobile Station"
entityID="00:0c:f1:53:9e:c0"/>

<AbsenceTrackEvent state="clear" entityType="Tag"
trackDefn="absenceDef1" entityID="00:0c:cc:5b:fc:da"/>
In/Out (Containment) Condition

Message format for element containment: 

<ContainmentTrackEvent
in="true | false" 
trackDefn="<name of track definition>"
containerType="Floor | Area | Network Design | Building" 
containerID="<fully quality name of container>" 
entityType="Mobile Station | Tag | Rogue AP | Rogue Client" 
entityID="<mac address"/>

Message format for the Clear state: 

<ContainmentTrackEvent
state="clear" 
trackDefn="<name of track definition>"
entityType="Mobile Station | Tag | Rogue AP | Rogue Client"
entityID="<mac address"/>

For example: 

<ContainmentTrackEvent in="true" trackDefn="myContainerRule1" 
containerType="Area" 
containerID="nycTestArea,5th Floor,Bldg-A,Rochester_Group,Rochester,"

Note

The containerID string represents a coverage area called nycTestArea, located in the 5th floor of Bldg-A of the campus Rochester. 

entityType="Tag" entityID="00:0c:cc:5b:fa:44"/>

<ContainmentTrackEvent state="clear" entityType="Tag" 
trackDefn="myContainerRule1" entityID="00:0c:cc:5b:f8:ab"/>
Distance Condition

Message format for elements on the same floor: 

<MovementTrackEvent
distance="<distance in feet at which the element was located>"
triggerDistance="<the distance specified on the condition"
reference="<name of the marker specified on the condition>" 
trackDefn="<name of event definition>"
entityType="Mobile Station | Tag | Rogue AP | Rogue Client" 
entityID="<mac address"/>

Message format for elements located on a different floor: 

<MovementTrackEvent optionMsg="has moved beyond original floor" 
reference="<name of the marker specified on the condition>" 
trackDefn="<name of event definition>"
entityType="Mobile Station | Tag | Rogue AP | Rogue Client" 
entityID="<mac address"/>

Message format for clear state: 

<MovementTrackEvent
state="clear" 
trackDefn="<name of event definition>"
entityType="Mobile Station | Tag | Rogue AP | Rogue Client" 
entityID="<mac address"/>

For example: 

<MovementTrackEvent distance="115.73819627990147" triggerDistance="60.0"
reference="marker2" trackDefn="distance2" entityType="Mobile Station"
entityID="00:0c:41:15:99:92"/>
<MovementTrackEvent optionMsg="has moved beyond original floor"
reference="marker2" entityType="Tag" 
trackDefn="distance2" 
entityID="00:0c:cc:5b:fa:4c"/>
<MovementTrackEvent state="clear" entityType="Tag"
Battery Level

Example:

<BatteryLifeTrackEvent lastSeen="10:28:52 08 Jun 2009" batteryStatus="medium" trackDefn="defn1" entityType="Tag" entityID="00:01:02:03:04:06"/>
Location Change

Example:

<MovementTrackEvent distance="158.11388300841898" triggerDistance="5.0"
reference="marker1" referenceObjectID="1" trackDefn="defn1" entityType="Mobile Station"
entityID="00:01:02:03:04:05"/>
Chokepoint Condition

Example: 

<ChokepointTrackEvent
lastSeen="11:10:08 PST 08 Jun 2009"
chokepointMac=“00:0c:cc:60:13:a3”
chokepointName= “chokeA3”
trackDefn=“choke"
entityType="Tag"
entityID="00:12:b8:00:20:4f”/>

An example for the Clear state follows: 

<ChokepointTrackEvent
state="clear" 
entityType="Tag"
trackDefn="choke"
entityID=”00:12:b8:00:20:4f”/>
Emergency Condition

An example for element location follows: 

<ChokepointTrackEvent
lastSeen=”11:36:46 PST June 08 2009"
emergencyReason= “detached”
trackDefn="emer"
entityType="Tag" 
entityID=”00:12:b8:00:20:50”/>

Note

Emergency events are never cleared.

Adding and Deleting Event Groups


Note

The Services > Context Aware Notifications page is available only in the root virtual domain.

Adding Event Groups

To add an event group, follow these steps:

    Step 1   Choose Services > Context Aware Notifications.
    Step 2   Choose Notification Definitions.
    Step 3   From the Select a command drop-down list, choose Add Event Group. Click Go.
    Step 4   Enter the name of the group in the Group Name text box.
    Step 5   Click Save.

    The new event group appears in the Event Settings page.

    Deleting Event Groups

    To delete an event group, follow these steps:

      Step 1   Choose Services > Context Aware Notifications.
      Step 2   Choose Notification Definitions.
      Step 3   Select the event group to delete by selecting its corresponding check box.
      Step 4   From the Select a command drop-down list, choose Delete Event Group, and then Click Go.
      Step 5   Click OK to confirm deletion.
      Step 6   Click Save.

      Adding, Deleting, and Testing event Definitions

      This section describes how to add, delete, and test event definitions and contains the following topics:

      Adding an Event Definition

      To add an event definition, follow these steps:

        Step 1   Choose Services > Context Aware Notifications.
        Step 2   From the left sidebar menu, choose Notification Definitions.
        Step 3   Click the name of the group to which you want to add an event definition. An event settings page appears showing existing event definitions for the event group.
        Step 4   From the Select a command drop-down list, choose Add Event Definition. Click Go.
        Step 5   At the Conditions tab, add one or more conditions. For each condition you add, specify the rules for triggering event notifications.
        Tip    For example, to keep track of heart monitors in a hospital, you might add rules to generate notifications when the following occur: (1) the heart monitor is missing for one hour, (2) the heart monitor moves off its assigned floor, or (3) the heart monitor enters a specific coverage area within a floor. In this example, add three separate rules to address these occurrences.

        To add a condition, follow these steps:

        1. Click Add to add a condition that triggers a notification.
        2. In the Add/Edit Condition dialog box, follow these steps:
          1. Choose a condition type from the Condition Type drop-down list.
            • If you chose Missing from the Condition Type drop-down list, enter the number of minutes after which a missing asset generates a notification. For example, if you enter 10 in this text box, the mobility services engine generates a missing asset notification if the MSE has not located the asset for more than 10 minutes after the device has become inactive or is no longer in the system. This condition occurs when the controller detects its absence and informs the MSE about it, or if the MSE does not hear anything about this device from the controller for 60 minutes by default. This value is configurable from the MSE command-line interface (accessible using cmdshell on the console) using the config mobile-node-inactive-in-minutes command for clients and config tag-inactive-time-in-minutes command for tags. Proceed to Step e.
            • If you choose In/Out from the Condition Type drop-down list, choose Inside of or Outside of, then click Select Area. Entry and exit of assets from the selected area is then monitored. In the Select dialog box, choose the area to monitor, then click Select. The area to monitor can be an entire campus, building within a campus, a floor in a building, or a coverage area (you can define a coverage area using the map editor). For example, to monitor part of a floor in a building, choose a campus from the Campus drop-down list, choose a building from the Building drop-down list, and choose the area to monitor from the Floor Area drop-down list. Then click Select. Proceed to Step e.
            • If you chose Distance from the Condition Type drop-down list, enter the distance in feet from a designated marker beyond which an asset triggers an event notification. Click Select Marker. In the Select dialog box, choose the campus, building, floor, and marker from the corresponding drop-down lists, and click Select. For example, if you add a marker to a floor plan and set the distance in the Trigger If text box to 60 feet, an event notification is generated if the monitored asset moves farther than 60 feet away from the marker. Proceed to Step e.
              Note   

              You can create markers and coverage areas using the Map Editor. When you create marker names, make sure they are unique across the entire system.

            • If you chose Battery Level from the Condition Type drop-down list, select the check box next to the appropriate battery level (low, medium, normal) that triggers a notification. Proceed to Step e.
            • If you chose Location Change from the Condition Type drop-down list, proceed to Step e.
            • If you chose Emergency from the Condition Type drop-down list, click the button next to the appropriate emergency (any, panic button, tampered, detached) that triggers a notification. Proceed to Step e.
            • If you chose Chokepoint from the Condition Type drop-down list, proceed to Step c. There is only one trigger condition and it is displayed by default. No configuration required.
        3. In the Trigger If text box, specify the time in minutes to trigger the notification. The default is 60 minutes.
        4. Select either Recurring or Non-recurring from the Notification Frequency radio button. If the frequency is non-recurring, the MSE sends absence notification only once. For recurring frequency, the MSE sends an absence notification periodically until the device becomes present again. Here period refers to the configured value in the absence definition.
        5. From the Apply To drop-down list, choose the type of asset (Any, Clients, Tags, Rogue APs, Rogue Clients, or Interferers) for which a notification is generated if the trigger condition is met.
          Note   

          If you choose Any from the Apply to drop-down list, the battery condition is applied to all tags, clients, rogue access points, and rogue clients.

          Note   

          Emergency and chokepoint notifications apply only to Cisco-compatible extension (CX) tags Version 1 or later.

        6. The Match By drop-down list contains the following choices, from left to right:
          • Choose the matching criteria (MAC Address, Asset Name, Asset Group, or Asset Category) from the first drop-down list.
          • Choose the operator (Equals or Like) from the second drop-down list.
          • Enter the relevant text into the text box based on the Match By criteria you chose. The following examples describe the asset matching criteria that you can specify:
            • If you choose MAC Address from the first drop-down list, choose Equals from the second drop-down list, and enter a MAC address (for example 12:12:12:12:12:12) in the text box, the event condition applies to the element whose MAC address is 12:12:12:12:12:12 (exact match).
            • If you choose MAC Address from the first drop-down list, choose Like from the second drop-down list, and enter 12:12 in the text box, the event condition applies to elements whose MAC address starts with 12:12.
              Note   

              If the MAC address is a partial MAC address, then it might cause a performance issue in Prime Infrastructure.

        7. Click Add to add the condition you have just defined.
          Note   

          If you are defining a chokepoint, you must select the chokepoint after you add the condition.

        Deleting an Event Definition

        To delete one or more event definitions from the Prime Infrastructure, follow these steps:

          Step 1   Choose Services > Context Aware Notifications.
          Step 2   Choose Notification Definitions.
          Step 3   Click the name of the group from which you want to delete an event definition.
          Step 4   Select the event definition that you want to delete by selecting its corresponding check box.
          Step 5   From the Select a command drop-down list, choose Delete Event Definition(s), and then click Go.
          Step 6   Click OK to confirm that you want to delete the selected event definition.

          Testing Event Definitions

          To test one or more event notifications of an event definition, follow these steps:

            Step 1   Choose Services > Context Aware Notifications.
            Step 2   Choose Notification Settings.
            Step 3   Click the name of the group containing the event definitions that you want to test.
            Step 4   Select the event definitions that you want to test by selecting their corresponding check boxes.
            Step 5   From the Select a command drop-down list, choose Test-Fire Event Definition(s), and then click Go.
            Step 6   Click OK to confirm that you want to test the event notifications.
            Step 7   Ensure that notifications were sent to the designated recipient.

            Prime Infrastructure as a Notification Listener

            Prime Infrastructure acts as a notification listener. It translates the traps into user interface alerts and shows them in the following formats:

            • Missing (Absence) Absence of Tag with MAC 00:0c:cc:5b:e4:1b, last seen at 16:19:45 08 June 2009.
            • In/Out (Containment) Tag with MAC 00:0c:cc:5b:fa:44 is In the Area 'Rochester > Rochester > 5th Floor > nycTestArea'
            • Distance 
              Tag with MAC 00:0c:cc:5b:fa:47 has moved beyond the distance configured for the marker 'marker2'.
Tag with MAC 00:0c:cc:5b:f9:b9 has moved beyond 46.0 ft. of marker 'marker2', located at a range of 136.74526528595058 ft.
            • Battery Level 
              Tag 00:01:02:03:04:06 has medium battery, last seen 11:06:01 08 June 2009
            • Location Change 
              Tag 00:01:02:03:04:06 has medium battery, last seen 11:06:01 08 June 2009
            • Location Change 
              Mobile Station 00:01:02:03:04:05 has moved
              158.11388300841898ft, where the trigger distance was 5.0