Getting information about alert definitions

Ops Center Analyzer Detail View REST API Reference Guide

Version
11.0.x
Audience
anonymous
Part Number
MK-99ANA004-10

You can obtain information for alert definitions through a single request.

Request line

baseURL/alertapi.do?action=retrieveAlertDef

Request body

{
  "defStatus":""
}

Request example using GET

GET /alertapi.do?action=retrieveAlertDef&defStatus=subscribed

Request example using POST

POST /alertapi.do?action=retrieveAlertDef
{
  "defStatus":"subscribed"
}

Request parameters

Note: If you do not specify the parameter value in the request, then all definitions present in the system are returned.

Parameters

Values

Description

defStatus String (Optional) Filter by definition status: created, subscribed, unsubscribed, and disabled.
owner String (Optional) Filter by definition owner (user who created the alert). A valid user on the Analyzer detail view.

Note: Any user can read alerts created by other users including admin.

For the Common Services user, use the following format:

user-name@CommonService

For example: sysadmin@CommonService
severity String (Optional) Filter by alert severity: critical or warning.
from String (Optional) Retrieve definitions created in a certain time window. This is the start of the time window in yyyyMMdd_HHmmss. By default, this timestamp is in the UTC time zone unless the utcOffset parameter is specified.
to String (Optional) Retrieve definitions created in a certain time window. This is end of the time window in yyyyMMdd_HHmmss. By default, this timestamp is assumed to be in the UTC time zone unless the utcOffset parameter is specified.
utcOffset String (Optional) UTC offset for from and to timestamps. The valid UTC offset string example: UTC+05:30, UTC-08:00
namePattern String (Optional) Filter by alert name. Regex matching the name of the definition.
resources String[ ] (Optional)

List of resource signatures.

Retrieve alerts configured for resources provided in this list.

Array of strings: Valid resource signatures for POST.

This parameter cannot be specified using HTTP GET.

alertIds Integer[ ] (Optional) Retrieve for specific list of alert IDs. If this list is provided, all the other parameters are ignored.

For HTTP GET, a comma-separated list of alert IDs.

For HTTP POST, an array of alert IDs

includeSubscription Boolean (Optional) Include subscription settings in output.

True or False

Default: False

includeResourceList Boolean (Optional) Include resources in output.

True or False

Default: False

resInstanceAlertsOnly Boolean (Optional) Retrieve definition of specific resource signatures.

True or False

If the value is true, then the retrieved list contains only those alert definitions whose signature matches the resources list.

Default: False

Note: The retrieve alert definition output displays advanced_properties used for creating alerts from the Analyzer detail view server UI. They contain information about the resource tree and are displayed when an alert is added through UI. (Otherwise, the values are displayed as null.)

.

Response body

{
  "retrieved":[
    {
      "alertId":,
      "name":"",
      "owner":"",
      "defStatus":"",
      "metric":"",
      "condition":"",
      "default_threshold":[
        , 
      ],
      "severity":"critical",
      "criteria":{
        "type":"",
        "m":,
        "n":,
        "n_unit":""
      },
      "resource_type":"",
      "resources":[
        {
          "signature":"",
          "threshold":[
            ,
          ]
        }
      ],
      "monitoring_window":{
        "to":"",
        "from":""
      },
      "subscriptions":[
        {
          "subscription":{
            "syslog":{
              "server":[ ]
            },
            "email":{
              "id":[
                ""
              ],
              "damping":""
            }
          },
          "user":""
        }
      ],
      "advanced_properties":{
        "category":null,
        "breadcrumb":null,
        "probe_type":null,
        "probe_ids":null,
        "sub_category":null,
        "category_resource_type":null,
        "category_tree_filter":null,
        "from_tree":false,
        "resource_filter":null,
        "parent_resource_key":null,
        "dynamic_resource_key":null,
        "resource_pattern":null,
        "resource_only":true
      }
    },
  ]
}

Response example

{
  "retrieved":[
    {
      "alertId":2,
      "name":"Sample AlertDef 2",
      "owner":"admin",
      "defStatus":"subscribed",
      "metric":"cpuUsage",
      "condition":"bt",
      "default_threshold":[
        30.0, 60.0
      ],
      "severity":"critical",
      "criteria":{
        "type":"m/n",
        "m":3,
        "n":5,
        "n_unit":"minutes"
      },
      "resource_type":"vm",
      "resources":[
        {
          "signature":"vm#vm2",
          "threshold":[
            20.0, 90.0
          ]
        }
      ],
      "monitoring_window":{
        "to":"23:59",
        "from":"10:00"
      },
      "subscriptions":[
        {
          "subscription":{
            "syslog":{
              "server":[ ]
            },
            "email":{
              "id":[
                "rah.shrma@culus.com"
              ],
              "damping":"no_damping"
            }
          },
          "user":"admin"
        }
      ],
      "advanced_properties":{
        "category":null,
        "breadcrumb":null,
        "probe_type":null,
        "probe_ids":null,
        "sub_category":null,
        "category_resource_type":null,
        "category_tree_filter":null,
        "from_tree":false,
        "resource_filter":null,
        "parent_resource_key":null,
        "dynamic_resource_key":null,
        "resource_pattern":null,
        "resource_only":true
      }
    },
    {
      "alertId":1,
      "name":"Sample AlertDef 1",
      "owner":"admin",
      "defStatus":"subscribed",
      "metric":"cpuUsage",
      "condition":"bt",
      "default_threshold":[
        10.0, 100.0
      ],
      "severity":"critical",
      "criteria":{
        "type":"m/n",
        "m":3,
        "n":5,
        "n_unit":"minutes"
      },
      "resource_type":"vm",
      "resources":[
        {
          "signature":"vm#vm1",
          "threshold":[
            10.0, 100.0
          ]
        },
        {
          "signature":"vm#vm2",
          "threshold":[
            10.0, 100.0
          ]
        }
      ],
      "monitoring_window":{
        "to":"23:59",
        "from":"10:00"
      },
      "subscriptions":[
        {
          "subscription":{
            "syslog":{
              "server":[ ]
            },
            "email":{
              "id":[
                "mj.w@cumls.com"
              ]
              "damping":"no_damping"
            }
          },
          "user":"admin"
        }
      ]
    }
  ]
}
Note: The input parameters includeSubscription and includeResourceList control verbosity of the response.
Response example for the configuration metrics:
{
  "retrieved": [
    {
      "alertId": 57,
      "name": "test_string_10",
      "owner": "admin",
      "defStatus": "unsubscribed",
      "metric": "dataSaving",
      "condition": "having",
      "default_threshold": [
        "Compression"
      ],
      "severity": "critical",
      "resource_type": "raidPool",
      "isSystemLevelAlert": false
    }
  ]
}

Status codes

Status code

Message

Description

400 BAD REQUEST Request URL or request body validation failed. Check the response body for details.

Response codes

The following table lists the alert API response codes that might be generated through the standard API. If an error response is not listed, examine the HTTP status codes to determine the best method for addressing the issue.
Response code Message Condition
A2020006 Invalid {from} is specified. Invalid from timestamp.
A2020006 Invalid {to} is specified. Invalid to timestamp.
A2020003 Mandatory parameter {from} is not specified. If to timestamp is specified but from is not specified.
A2020003 Mandatory parameter {to} is not specified. If from timestamp is specified but to is not specified.
A2020006 Invalid {defStatus} is specified. Invalid defStatus.
A2020006 Invalid {severity} is specified. Invalid severity.
A2020006 Invalid {namePattern} is specified. Invalid regex is specified in the namePattern.
A2020015 Time window is not specified for the utcOffset. Time window is not specified for utcOffset.
A2020006 Invalid {utcOffset} is specified. Invalid utcOffset.
A2000013 Application encountered internal error. API server encountered an internal error.
A2020019 Found invalid properties [resource, unknownKey]. Invalid key is specified.