Alarm Calls

uimpga-ga
Contents
2
All alarm calls are supported by both ems and nas. However, ems does not support the use of nas probe callbacks. For example, you cannot update custom fields in ems alarm messages using the nas
set_alarm
callback.
Also, alarms originating from the ems probe have one of the following items appended to the end of their alarm IDs:
  • ems 8.41 or later -
    __ems
  • ems 8.4 -
    :ems
Create an Alarm
The
severity
and
message
fields are required when creating an alarm. The message field sets the alarm message. The severity field indicates the impact or importance of an alarm. The following numeric values are supported:
  • 0
    – Clear (Indicates that a component has returned to a normal state).
  • 1
    – Informational
  • 2
    – Warning
  • 3
    – Minor
  • 4
    – Major
  • 5
    – Critical
URL
/alarms/createAlarm
Method
POST
Returns
  • 204 No Content
  • 401 Unauthorized
  • 404 Not Found
Valid Users
  • Bus users
Required Permissions
  • Alarm Management
  • Web Service
JSON
Sample Request
  In order to return a value for
metId
, the parameters
ciType
and
ciName
also must be set.
POST /rest/alarms/createAlarm HTTP/1.1 Accept: application/JSON Content-Type: application/JSON { "level":"1", "message":"Testmessage", "metId":"MD8110AB685AA9D19C8F7F807FDAC306F", "severity":"Informational", "source":"w2k8r2-x64-lc", "subsystemId":"1", "suppressionKey":"", "ciType":"1.1.2", "ciName":"Disk Usage", "custom1":"A custom property 1", "custom2":"A custom property 2", "custom3":"A custom property 3", "custom4":"A custom property 4", "custom5":"A custom property 5" }
Sample Reply
HTTP/1.1 204 No Content
XML
Sample Request
In order to return a value for
metId
, the parameters
ciType
and
ciName
also must be set.
POST /rest/alarms/createAlarm HTTP/1.1 Accept: application/xml Content-Type: application/xml <alarm> <level>1</level> <message>Testmessage</message> <metId>MD8110AB685AA9D19C8F7F807FDAC306F</metId> <severity>Informational</severity> <source>w2k8r2-x64-lc</source> ?<subsystemId>1</subsystemId> <suppressionKey></suppressionKey> <ciType>1.1.2</ciType> <ciName>Disk Usage</ciName> <custom1>A custom property 1</custom1> <custom2>A custom property 2</custom2> <custom3>A custom property 3</custom3> <custom4>A custom property 4</custom4> <custom5>A custom property 5</custom5> </alarm>
Sample Reply
HTTP/1.1 204 No Content
Create a Custom Alarm Property
You can use this endpoint to set more than one alarm property. However, you cannot set the custom properties on more than one alarm at once.
URL
/rest/alarms/{alarmId}/set_custom_property
Method
POST
Returns
  • 204 No Content - OK
  • 401 Unauthorized
  • 404 Not Found
Valid Users
  • Bus user
Required Permissions
  • Alarm Management
  • Web Service
JSON
Sample Request
POST /rest/alarms/UV08021146-14914/set_custom_property HTTP/1.1 Accept: application/json Content-Type: application/json { "alarm_property" : { [ "key" : "custom_1", "value" : "value for custom_1" } "key" : "custom_2", "value" : "value for custom_2" }?] }
Sample Reply
HTTP/1.1 204 No Content
XML
Sample Request
POST /rest/alarms/UV08021146-14914/set_custom_property HTTP/1.1 Accept: application/xml Content-Type: application/xml <alarm_properties> <alarm_property> <key>custom_1</key> <value>value for custom_1</value> </alarm_property> <alarm_property> <key>custom_2</key> <value>value for custom_2</value> </alarm_property> </alarm_properties>
Sample Reply
HTTP/1.1 204 No Content
Get Alarm Summary
Returns a structure containing alarm counts for the different alarm severities.
URL
/alarms/summary
Method
GET
Returns
  • 200 OK & AlarmSummary structure (XML/JSON)
  • 401 Unauthorized
  • 404 Not Found
Valid Users
  • Bus users
  • Account contact users
Required Permissions
  • Alarm Summary
  • Web Service
JSON
Sample Request
GET /rest/alarms/summary HTTP/1.1 Accept: application/json
Sample Reply
HTTP/1.1 200 OK Content-Type: application/json { "clear":"0", "critical":"7", "information":"24", "major":"9", "minor":"6", "warning":"6" }
XML
Sample Request
GET /rest/alarms/summary HTTP/1.1 Accept: application/xml
Sample Reply
HTTP/1.1 200 OK <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <alarmsummary> <clear>0</clear> <critical>12</critical> <information>47</information> <major>19</major> <minor>9</minor> <warning>13</warning> </alarmsummary>
Get Alarm List (Filtered)
This call returns a filtered list of alarms that are visible to the user. For details on the Alarm Filter structure passed to this call, refer to the section Alarm Filters .
URL
/alarms
Method
POST
Returns
  • 200 OK & AlarmListDocument XML/JSON
  • 401 Unauthorized
  • 404 Not Found
Valid Users
  • Account contact users
  • Bus users
Required Permissions
  • Alarm Details
  • Web Service
JSON
Sample Request
POST /rest/alarms HTTP/1.1
Accept: application/json
Content-Type: application/json
{
"assigned_to":"userA",
"includeClosed":"only",
"deviceIds":"DCC87D8A5B58DE6268A9C178D490F9C96”,
"custom1":"lorum",
"custom2":"ipsum",
"custom3":"dolor",
"custom4":"sit",
"custom5":"amet",
"domain":"domainA",
"hostname":"hostA",
"hub":"hubB",
"level":"2,3,4,5,6",
"message":"message text to search for",
"message_count":">2",
"origin":"customerA",
"probe":"cdm",
"robot":"robotC",
"source":"maecenas",
"subsystem":"cpu",
"subsystem_id":"1.3.1",
"timeArrival":"2011-11-22T12:54:35+01:00",
"timeLast":"2011-11-22T12:54:35+01:00",
"userTag1":"utag1",
"userTag2":"utag2",
"visible":"true"
}
Sample Reply
HTTP/1.1 200 OK Content-Type: application/json Transfer-Encoding: chunked 2000 {"alarm": [ { "assignedBy":"", "assignedTo":"", "custom1":"", "custom2":"", "custom3":"", "custom4":"", "custom5":"", "domain":"chris-dev", "hostname":"win-cxp6lpt7v6g", "hub":"primaryhub", "id":"RH99670515-00059", "level":"1", "message":"USER32(1074 - None): The process C:\\Windows\\system32\\winlogon.exe (WIN-CXP6LPT7V6G) has initiated the power off of computer WIN-CXP6LPT7V6G.", "nas":"primaryhub", "origin":"primaryhub", "prevLevel":"0", "probe":"ntevl", "robot":"win-cxp6lpt7v6g", "severity":"Informational", "source":"192.168.211.129", "subsystem":"System", "subsystemId":"1.1.11.1.3", "suppressionCount":"0", "suppressionKey":"", "timeArrival":"2011-11-11T09:51:45+01:00", "timeOrigin":"2011-11-11T09:51:43+01:00", "timeLast":"2011-11-11T09:51:45+01:00", "userTag1":"", "userTag2":"", "visible":"true" },{ "assignedBy":"", "assignedTo":"", ... } ]}
XML
Sample Request
POST /rest/alarms HTTP/1.1 Accept: application/xml Content-Type: application/xml <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <alarmfilter> <level>2,3,4,5</level> </alarmfilter>?
Sample Reply
HTTP/1.1 200 OK Content-Type: application/xml <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <alarm-list> <alarm> <assignedBy></assignedBy> <assignedTo></assignedTo> <custom1></custom1> <custom2></custom2> <custom3></custom3> <custom4></custom4> <custom5></custom5> <domain>chris-dev</domain> <hostname>MFC7840W</hostname> <hub>primaryhub</hub> <id>DL31165458-84280</id> <level>5</level> <message>The SNMP agent on '192.168.0.119' is NOT responding.</message> <nas>primaryhub</nas> <origin>primaryhub</origin> <prevLevel>0</prevLevel> <probe>interface_traffic</probe> <robot>win-cxp6lpt7v6g</robot> <severity>Critical</severity> <source>MFC7840W</source> <subsystem>Network</subsystem> <subsystemId>1.1.3</subsystemId> <suppressionCount>0</suppressionCount> <suppressionKey>NetTfc/state-192.168.0.119</suppressionKey> <timeArrival>2011-11-02T11:27:40+01:00</timeArrival> <timeOrigin>2011-11-02T11:27:39+01:00</timeOrigin> <timeLast>2011-11-02T11:27:40+01:00</timeLast> <userTag1></userTag1> <userTag2></userTag2> <visible>true</visible> </alarm> <alarm> <assignedBy></assignedBy> <assignedTo></assignedTo> <custom1></custom1> ... </alarm> </alarm-list>
Get Alarm List (Unfiltered)
This call returns all alarms that are visible to the user.
URL
/alarms
Method
GET
Query Parameters
alarmId=<alarmId> (results will be limited to the alarmId specified)
device=true|false   (default=false.  If true, the specifics of the device against which the alarm was specified will be returned instead of the contents of the alarm.)
Returns
  • 200 OK & AlarmListDocument XML/JSON
  • 401 Unauthorized
  • 404 Not Found
Valid Users
  • Account contact users
  • Bus users
Required Permissions
  • Alarm Details
  • Web Service
JSON
Sample Request 1
GET /rest/alarms HTTP/1.1 Accept: application/json
Sample Reply 1
HTTP/1.1 200 OK Content-Type: application/json Transfer-Encoding: chunked 2000 {"alarm": [ { "assignedBy":"", "assignedTo":"", "custom1":"", "custom2":"", "custom3":"", "custom4":"", "custom5":"", "domain":"chris-dev", "hostname":"win-cxp6lpt7v6g", "hub":"primaryhub", "id":"RH99670515-00059", "level":"1", "message":"USER32(1074 - None): The process C:\\Windows\\system32\\winlogon.exe (WIN-CXP6LPT7V6G) has initiated the power off of computer WIN-CXP6LPT7V6G.", "nas":"primaryhub", "origin":"primaryhub", "prevLevel":"0", "probe":"ntevl", "robot":"win-cxp6lpt7v6g", "severity":"Informational", "source":"192.168.211.129", "subsystem":"System", "subsystemId":"1.1.11.1.3", "suppressionCount":"0", "suppressionKey":"", "timeArrival":"2011-11-11T09:51:45+01:00", "timeOrigin":"2011-11-11T09:51:43+01:00", "timeLast":"2011-11-11T09:51:45+01:00", "userTag1":"", "userTag2":"", "visible":"true" },{ "assignedBy":"", "assignedTo":"", ... } ]}
Sample Request 2
GET /rest/alarms?alarmId=LJ95103405-43107&device=true HTTP/1.1
Accept: application/json
Sample Reply 2
HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked
2000
{
"alarmId": "LJ95103405-43107",
"csId": "1",
"dedicated": "VirtualMachine",
"ip": "10.238.42.211",
"mac": "00-50-56-9D-AF-C4",
"name": "testSqlserver",
"origin": "testSqlserver_hub",
"osDescription": "Service Pack 1 Build 7601",
"osName": "WindowsServer-2008-R2",
"osType": "Windows",
"osVersion": "6.1.7601"
}
XML
Sample Request
GET /rest/alarms HTTP/1.1 Accept: application/xml
Sample Reply
HTTP/1.1 200 OK Content-Type: application/xml <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <alarm-list> <alarm> <assignedBy></assignedBy> <assignedTo></assignedTo> <custom1></custom1> <custom2></custom2> <custom3></custom3> <custom4></custom4> <custom5></custom5> <domain>chris-dev</domain> <hostname>MFC7840W</hostname> <hub>primaryhub</hub> <id>DL31165458-84280</id> <level>5</level> <message>The SNMP agent on '192.168.0.119' is NOT responding.</message> <nas>primaryhub</nas> <origin>primaryhub</origin> <prevLevel>0</prevLevel> <probe>interface_traffic</probe> <robot>win-cxp6lpt7v6g</robot> <severity>Critical</severity> <source>MFC7840W</source> <subsystem>Network</subsystem> <subsystemId>1.1.3</subsystemId> <suppressionCount>0</suppressionCount> <suppressionKey>NetTfc/state-192.168.0.119</suppressionKey> <timeArrival>2011-11-02T11:27:40+01:00</timeArrival> <timeOrigin>2011-11-02T11:27:39+01:00</timeOrigin> <timeLast>2011-11-02T11:27:40+01:00</timeLast> <userTag1></userTag1> <userTag2></userTag2> <visible>true</visible> </alarm> <alarm> <assignedBy></assignedBy> <assignedTo></assignedTo> <custom1></custom1> ... </alarm>
Get Alarm State (All)
This call returns the severity of the most critical alarm currently visible to the user.
URL
/alarms/state
Method
GET
Returns
  • 200 OK & AlarmSeverity structure XML/JSON
  • 401 Unauthorized
  • 404 Not Found
Valid Users
  • Account contact users
  • Bus users
Required Permissions
  • Alarm Summary
  • Web Service
JSON
Sample Request
GET /rest/alarms/state HTTP/1.1 Accept: application/json
Sample Reply
HTTP/1.1 200 OK Content-Type: application/json { "level":"5", "severity":"Critical" }
XML
Sample Request
GET /rest/alarms/state HTTP/1.1 Accept: application/xml
Sample Reply
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <alarm-severity> <level>5</level> <severity>Critical</severity> </alarm-severity>
Get Alarm State (Filtered)
This call returns the severity of the most critical alarm currently open that matches the given alarm filter. For details on the Alarm Filter structure passed to this call, refer to the section Alarm Filters.
URL
/alarms/state
Method
Post
Inputs
  • AlarmFilter structure
Returns
  • 200 OK & AlarmSeverity structure XML/JSON
  • 401 Unauthorized
  • 404 Not Found
Valid Users
  • Account contact users
  • Bus users
Required Permissions
  • Alarm Summary
  • Web Service
JSON
Sample Request
POST /rest/alarms/state HTTP/1.1 Accept: application/json Content-Type: application/json { "assigned_to":"userA", "includeClosed":"only", "deviceIds":" DCC87D8A5B58DE6268A9C178D490F9C96", ? "custom1":"lorum", "custom2":"ipsum", "custom3":"dolor", "custom4":"sit", "custom5":"amet", "domain":"domainA", "hostname":"hostA", "hub":"hubB", "level":"2,3,4,5,6", "message":"message text to search for", "message_count":">2", "origin":"customerA", "probe":"cdm", "robot":"robotC", "source":"maecenas", "subsystem":"cpu", "subsystem_id":"1.3.1", "timeArrival":"2011-11-22T12:54:35+01:00", "timeLast":"2011-11-22T12:54:35+01:00", "userTag1":"utag1", "userTag2":"utag2", "visible":"true" }
Sample Reply
HTTP/1.1 200 OK Content-Type: application/json
XML
Sample Request
POST /rest/alarms/state HTTP/1.1 Accept: application/xml Content-Type: application/xml <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <alarmfilter> <level>2,3,4,5,6</level> </alarmfilter> Filtering by assigned person: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <alarmfilter> <assigned_to>administrator</assigned_to> </alarmfilter> Filtering by alarm id: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <alarmfilter> <id>LC29347578-03846</id> </alarmfilter>
Sample Reply
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <alarm-severity> <level>5</level> <severity>Critical</severity> </alarm-severity>
Update an Alarm (Accept)
URL
/alarms/{alarmid}/accept
Method
PUT
Returns
  • 204 No Content - OK
  • 401 Unauthorized
  • 404 Not Found
Valid Users
  • Bus users
Required Permissions
  • Accept
  • Web Service
Sample Request
PUT /rest/alarms/DL31165458-85308/accept HTTP/1.1
Sample Reply
HTTP/1.1 204 No Content
Update an Alarm (Acknowledge)
URL
/alarms/{alarmid}/ack
Method
PUT
Returns
  • 204 No Content - OK
  • 401 Unauthorized
  • 404 Not Found
Valid Users
  • Bus users
Required Permissions
  • Acknowledge
  • Web Service
Sample Request
PUT /rest/alarms/DL31165458-85308/ack HTTP/1.1
Sample Reply
HTTP/1.1 204 No Content
Update an Alarm (Assign)
URL
/alarms/{alarmid}/assign/{assignToUsername}
Method
PUT
Returns
  • 204 No Content - OK
  • 401 Unauthorized
  • 404 Not Found
Valid Users
  • Bus user
Required Permissions
  • Assign
  • Web Service
Sample Request
PUT /rest/alarms/DL31165458-85308/assign/operatorA HTTP/1.1
Sample Reply
HTTP/1.1 204 No Content
Update an Alarm (Unassign)
URL
/alarms/{alarmid}/unassign
Method
PUT
Returns
  • 204 No Content - OK
  • 401 Unauthorized
  • 404 Not Found
Valid Users
  • Bus user
Required Permissions
  • Unassign
  • Web Service
Sample Request
PUT /rest/alarms/DL31165458-85308/unassign HTTP/1.1
Sample Reply
HTTP/1.1 204 No Content?
Alarm Filters
Alarm-related calls use the following filter fields:
Field
Description
id
The alarm id (nimid) of the alarm.
includeClosed
A flag specifying whether or not to include closed alarms in the list of alarms returned.
false = (default) Do not include any closed alarms in the returned list
true = Include closed alarms in the list  (This means BOTH open and closed alarms)
only = Include ONLY closed alarms in the list.  No open alarms will be included.
deviceIds
A single device Id or comma-separated list of deviceIds against which to limit the alarms returned.
A device Id will have the same syntax as: DCC87D8A5B58DE6268A9C178D490F9C96
level
A comma-separated list of all levels that should be returned, where:
1 = Information, 2 = Warning, 3 = Minor, 4 = Major, 5 = Critical
hostname
The hostname.
source
The alarm source.
domain
The domain of the alarm.
hub
The hub of the alarm. This contains the first hub that received the alarm.
robot
The robot name that raised the alarm.
probe
The name of the probe that raised the alarm.
subsystem_id
The subsystem_id of the alarm. See the subsystem-tree in the alarm server (nas).
subsystem
The subsystem name of the alarm. See the subsystem-tree in the alarm server (nas).
origin
The origin of the alarm.
message_count
The amount of times that this alarm has recurred.
The value should be an operator and an integer value.
For Json, valid operators: “=”, “<=” , “<”, “>=”, “>”, “!=”
e.g. “>2” will only return alarms that recurred more than twice.
For xml, valid operators: “=”, “&lt;=”, “&lt;”, “&gt;=”, “&gt;”, “!=”
e.g. “&gt;2” will only return alarms that recurred more than twice.
message
The message text of the alarm.
userTag1
The value of the user tag 1.
userTag2
The value of the user tag 2.
custom1
The value of the custom field 1.
custom2
The value of the custom field 2.
custom3
The value of the custom field 3.
custom4
The value of the custom field 4.
custom5
The value of the custom field 5.
assigned_to
The name of the user the alarm is currently assigned to.
timeArrival
A date time value (format: 2011-12-15T01:35:55.524+01:00) specifying the start of the filter time. Only alarms that arrived at the alarm server after this date will be returned.
timeLast
The time the alarm was last updated.
visible
This is a Boolean. Valid values are:
  • False
  • True
If set to true, only visible alarms are returned. If set to false, only invisible alarms are returned.