Overview¶

The documentation in this section describes the RESTful APIs included with AppResponse 11. It is assumed that the reader has practical knowledge of RESTful APIs, so the documentation does not go into detail about what REST is, and how to use it. Instead, the documentation focuses on what data can be accessed, and how to access it.

The APIs are versioned using the Semantic Versioning rules.

When it comes to programmatically accessing REST APIs, Riverbed strongly recommends using the SteelScript for Python SDK. With SteelScript for Python, you can:

Get started quickly based on example scripts.
Develop applications faster by leveraging the vast number of modules available for Python.
Build upon shared code samples from the Riverbed and Python communities.

Concepts for subscribing to System Health notifications¶

Introduction¶

Notifications (emails, SNMP traps/informs, ServiceNow alerts, etc.) are initiated from the system in response to various internal events, and delivered to the notification endpoints as configured by the end user. Configuration of the delivery mechanisms and the endpoints are is handled through the npm.usernotify REST API.

System Health alerts are generated by the npm.health service, and the names of health alerts that generate notifications can be enumerated from this API so that they can be subscribed to.

Configuring subscriptions for System Health notifications requires several steps:

Optionally create a Recipient object with npm.usernotify to group notification endpoints together.
Obtain the System Health alert notification_id to subscribe to, and determine the alert severity levels that these endpoints should be notified for.
Subscribe Recipients and/or email addressees to the desired notification_id at these severity levels.

Subscriptions can be removed and updated to change the endpoints that receive these notifications, or to stop receiving notifications, at each alert severity level.

Glossary¶

Delivery Type - A handler for sending notifications to a type of endpoint. E.g., email, SNMP, ServiceNow, Syslog. A Delivery Type requires information about a Notification Endpoint in order to deliver a notification. Delivery Types may have their own global configuration that applies to all endpoints (e.g., to set an SMTP server for email delivery).

Notification Endpoint - Also referred to as an addressee. A descriptor for where a notification is sent. E.g., an email address, an SNMP endpoint address, a Syslog server, or a ServiceNow server. Endpoints may have their own settings (e.g., SNMP connection parameters, ServiceNow authentication) for delivering a notification to that endpoint.

Recipient - An object that contains one or more Notification Endpoints definitions, allowing a notification to be sent to multiple endpoints at the same time.

Notification Type - A class of notification that may be sent from the system upon certain events. Contrast with Notification Event below. Subscriptions to a Notification Type will result in Notification Events being delivered to the subscribed Recipients.

Notification Event - An instance of a Notification Type occurring at a specific time that is delivered to any subscribed Recipients and endpoints.

Alert - A specific subset of Notification Types and Events that represents an unexpected or exceptional condition of the system. Alerts have a severity and additional details relevant to the type of alert. Alerts also have a duration and an alerting policy, which specifies whether subscribed endpoints receive both “Start” and “End” notifications, or just momentary notifications that an event occurred, and whether notifications are sent if the Alert ends and recurs within a given time period.

Health Severity - A string identifier categorizing the relative importance of System Health node statuses, one of “critical”, “major” or “minor”. Each System Health Node supports a different set of severities, listed on the alert_definition.alert_severities array property, which maps this string value (as name) to its numeric Severity Level (see below) as level.

Alert Severity Level - A numeric severity level equivalent to each of the Health Severities listed above, used for alerting and subscribing to alert notifications.

Subscription - An object associating Recipients and additional endpoints to a Notification Type, to receive notifications under matching conditions. Subscriptions can restrict whether a Notification Event is delivered to the Recipient/endpoints, e.g., based on alert severity for System Health alerts.

Delivery Type object¶

Delivery types record the supported methods for delivering notifications and any global configuration needed for performing the delivery.

Delivery Types have two relevant properties:

name - String (read-only). The identifier for this delivery type. Addressees for this delivery type will use a matching string as their delivery_type property.

options - Object. Holds global configuration for the delivery type, e.g., SMTP server details for the “email” delivery type. Only the “email” delivery type uses this configuration data, as discussed below.

Example¶

Delivery Type definitions can be enumerated to see the list of supported delivery types.

--> GET /api/npm.usernotify/3.0/delivery_types
{
  "items": [
    {
      "active": true,
      "enabled": true,
      "name": "syslog",
      "options": {}
    },
    {
      "active": true,
      "enabled": true,
      "name": "snmp",
      "options": {}
    },
    ...
}

And individual delivery types are addressable by name:

--> GET /api/npm.usernotify/3.0/delivery_types/items/email
{
  "active": true,
  "enabled": true,
  "name": "email",
  "options": {
    "username": "",
    "from": "Riverbed SteelCentral AppResponse 11 <root@localhost>",
    "host": "",
    "smtp_timeout": 30,
    "security": "NONE",
    "port": 25
  }
}

Email Delivery Configuration¶

Using email delivery type requires an SMTP server to handle the outgoing mail, and this is configured via the options property on the “email” delivery_type object.

Fetch the email delivery_type and modify the settings in options to change these values to match your SMTP server settings as below:

username - String. The username (if authentication is required) to login as. Only the PLAIN SMTP authentication method is supported.

new_password - String (write-only). Password to use to authenticate with the server.

from - String. An email address (“noreply@company.com”) or email address with name (“Your Name Here <noreply@company.com>”) to specify the Sender the emails should appear to be from.

security - String, one of “NONE”, “SSL” or “STARTTLS”. Type of connection security to use. “NONE” uses no encryption and does not protect the username/password information. “SSL” (implicit SSL/TLS) connects initially on an encrypted channel. “STARTTLS” (explicit SSL/TLS) connects unencrypted and then requests enabling encryption with the server.

host - String. SMTP server hostname or IP address.

port - Integer. Port of the SMTP server.

smtp_timeout - Integer (non-zero). Amount of time to wait for the SMTP connection before failing delivery. Failed email deliveries are not re-attempted.

Example¶

--> PUT /api/npm.usernotify/3.0/delivery_types/items/email
{
  "active": true,
  "enabled": true,
  "name": "email",
  "options": {
    "username": "user@company.com",
    "new_password": "Secret!word",
    "from": "Alert Sender <noreply-alerts@company.com>",
    "host": "smtp.company.com",
    "smtp_timeout": 60,
    "security": "STARTTLS",
    "port": 587
  }
}
<-- 200 OK
...
Response body:
{
  "active": true,
  "enabled": true,
  "name": "email",
  "options": {
    "username": "user@company.com",
    "from": "Alert Sender <noreply-alerts@company.com>",
    "host": "smtp.company.com",
    "smtp_timeout": 60,
    "security": "STARTTLS",
    "port": 587
  }
}

Recipient object¶

Recipients record one or more endpoints for any of the supported delivery types. Recipients can be created, modified and deleted. A recipient that is currently subscribed to one or more Notification Types cannot be deleted until all Subscriptions using it have been deleted.

Recipients have these properties:

id - Integer (read-only). A unique identifier created by the server upon creation. Omit this when creating new recipients.

name - String. A human-readable name for describing the Recipient.

addressees - Array of addressee objects (see below).

Examples¶

Recipients are enumerable at the /recipients API:

--> GET
/api/npm.usernotify/3.0/recipients
{
  "items": [
    {
      "id": 1,
      "name": "Alert Recipients Group",
      "addressees": [
        {
          "to": [
            "sysadmin@company.com",
            "alert-list@company.com"
          ],
          "delivery_type": "email"
        },
        {
          "delivery_type": "snmp",
          "version": "1",
          "address": "snmpreceiver.company.com"
        }
      ]
    }
  ]
}

Recipients can be individually addressed and modified by id:

--> GET /api/npm.usernotify/3.0/recipient/items/1
{
  "id": 1,
  "name": "Alert Recipients Group",
  "addressees": [
    {
      "to": [
        "sysadmin@company.com",
        "alert-list@company.com"
      ],
      "delivery_type": "email"
    },
    {
      "delivery_type": "snmp",
      "version": "1",
      "address": "snmpreceiver.company.com"
    }
  ]
}

--> PUT /api/npm.usernotify/3.0/recipient/items/1
{
  "id": 1,
  "name": "Updated Alert Recipients Group",
  "addressees": [
    {
      "to": [
        "alert-list@company.com"
      ],
      "delivery_type": "email"
    }
  ]
}
<-- 200 OK
...
Response body:
{
  "id": 1,
  "name": "Updated Alert Recipients Group",
  "addressees": [
    {
      "to": [
        "alert-list@company.com"
      ],
      "delivery_type": "email"
    }
  ]
}

Creating a recipient requires a POST to /recipients with the new Recipient object.

--> POST /api/npm.usernotify/3.0/recipients
{
  "name": "Alert Recipients Group",
  "addressees": [
      {
        "delivery_type": "email",
        "to": ["sysadmin@company.com", "alert-list@company.com"]
      },
      {
        "delivery_type": "snmp",
        "address": "snmpreceiver.company.com",
        "version": "1",
        "new_community": "public"
      }
   ]
}
<-- 201 Created
...
Response body:
{
  "id": 1,
  "name": "Alert Recipients Group",
  "addressees": [
    {
      "to": [
        "sysadmin@company.com",
        "alert-list@company.com"
      ],
      "delivery_type": "email"
    },
    {
      "delivery_type": "snmp",
      "version": "1",
      "address": "snmpreceiver.company.com"
    }
  ]
}

Addressee objects¶

Addressee objects are constituents of Recipient and Subscription objects, identifying where notifications should be sent via the indicated methods.

Each addressee object contains a delivery_type property identifying the type of addressee, and other properties vary depending on this delivery type.

Refer to the npm.usernotify API reference for a complete list of delivery types and the properties supported on their addressee objects.

System Health Alert Notifications¶

System Health Alert Notifications are a type of notification generated when an exceptional condition is detected on the system. Details about the alert itself can be found in the Alert Events Insight, and the details are also included with the notification event that is sent to compatible addressees.

To list available System Health notifications, use the npm.health API to enumerate the health_nodes object.

Information on these objects relevant for subscribing to alerts includes:

id - String. Identifier used by the npm.health service to identify this Health Node.

alert_definition.notification_id - String. This identifier is used as the notification_id field for subscriptions to this alert, and may be different from id.

alert_definition.alert_severities - Array of objects. Each object specifies a severity name indicating whether the alert may fire at a “minor”, “major” or “critical” level. Different alerts support different alert levels.

alert_definition.alert_type - String. One of “discrete” or “continuous”. Discrete alerts fire once per event and have no duration. Continuous alerts start at a given time, and end at a later time when the problematic condition stops occurring. This value is not used when creating subscriptions, it is informational to understand how and when alerts will be delivered.

To subscribe to an alert, a separate Subscription object must be created for each alert severity for which the endpoint(s) should receive a notification. E.g., to subscribe a Recipient to a health.analysis_packet_drops alerts of severity major or greater (i.e., major or critical), two Subscription objects are necessary, one at each level.

Examples¶

Health nodes can be enumerated with /health_nodes:

--> GET /api/npm.health/1.1/health_nodes
{
  "items": [
    ...
    {
      "category": "traffic",
      "name": "Analysis Packet Drops",
      "parameters": [
        {
          "default_value": 5,
          "description": "# of consecutive minutes with drops to trigger the alert",
          "validations": [
            {
              "validation": "range",
              "minimum": 5,
              "maximum": 60
            }
          ],
          "value": 5,
          "parameter_type": "integer",
          "id": "consecutive_minutes",
          "name": "Consecutive Minutes with Drops"
        },
        {
          "default_value": 20.0,
          "description": "% of dropped packets triggering a critical alert",
          "validations": [
            {
              "validation": "range",
              "minimum": 0.0,
              "maximum": 100.0
            },
            {
              "validation": "parameter",
              "id": "major_threshold",
              "constraint": "greater_than"
            }
          ],
          "value": 20.0,
          "parameter_type": "number",
          "id": "critical_threshold",
          "name": "Critical Threshold (%)"
        },
        {
          "default_value": true,
          "description": "Health node is enabled",
          "validations": [],
          "value": true,
          "parameter_type": "boolean",
          "id": "enabled",
          "name": "enabled"
        },
        {
          "default_value": 10.0,
          "description": "% of dropped packets triggering a major alert",
          "validations": [
            {
              "validation": "range",
              "minimum": 0.0,
              "maximum": 100.0
            },
            {
              "validation": "parameter",
              "id": "minor_threshold",
              "constraint": "greater_than"
            }
          ],
          "value": 10.0,
          "parameter_type": "number",
          "id": "major_threshold",
          "name": "Major Threshold (%)"
        },
        {
          "default_value": 5.0,
          "description": "% of dropped packets triggering a minor alert",
          "validations": [
            {
              "validation": "range",
              "minimum": 0.0,
              "maximum": 100.0
            }
          ],
          "value": 5.0,
          "parameter_type": "number",
          "id": "minor_threshold",
          "name": "Minor Threshold (%)"
        }
      ],
      "children": [],
      "parent_id": "health",
      "alert_definition": {
        "notification_id": "health.analysis_packet_drops",
        "alert_severities": [
          {
            "name": "minor",
            "level": 2
          },
          {
            "name": "major",
            "level": 3
          },
          {
            "name": "critical",
            "level": 4
          }
        ],
        "alert_type": "continuous"
      },
      "id": "health.analysis_packet_drops",
      "description": "Health of the analysis packet pipeline"
    },
    ...
  ]
}

Individual health nodes are addressable by id at /health_nodes/items/<id>:

--> GET /api/npm.health/1.1/health_nodes/items/health.coredump
{
  "category": "software",
  "name": "Coredump Detected",
  "parameters": [
    {
      "default_value": true,
      "description": "Health node is enabled",
      "validations": [],
      "value": true,
      "parameter_type": "boolean",
      "id": "enabled",
      "name": "enabled"
    }
  ],
  "children": [],
  "parent_id": "health",
  "alert_definition": {
    "notification_id": "health.coredump",
    "alert_severities": [
      {
        "name": "minor",
        "level": 2
      }
    ],
    "alert_type": "discrete"
  },
  "id": "health.coredump",
  "description": "Tracks coredumps generated by system processes"
}

Subscription objects¶

Subscriptions specify which Recipients (and optionally additional endpoints) should receive a type of notification using these properties:

id - Integer. Automatically supplied by the server upon creation. Omit this property when creating new subscriptions.

notification_id - String. Identifier for the notification type being subscribed to, obtained from alert_definition.notification_id on the Health Node.

recipient_ids - Array of integers. Each integer is the integer id of a Recipient who should receive this type of notification, as enumerated from the npm.usernotify service. May be an empty array if addressees is used.

addressees - Array of Email addressee objects. May be an empty array. Specifies email addressees to receive this notification in addition to the Recipients above. Only “email” type addressees are supported in this array.

filter - Object specifying conditions of the notification event being sent under which the recipients should receive this notification. Discussed in more detail below.

Because each subscription object subscribes the Recipients and addressees to only one severity level for the given alert, it is necessary to create multiple Subscription objects for the same set of Recipients and addressees, one for each severity level of concern, and for each higher severity level, in order to maintain consistency when alerts transition to higher and lower severities.

Subscribing to a lower severity level does not automatically cause notifications to be delivered for higher severity levels as well. Multiple Subscription objects with different severities are required to achieve this.

Some Health Nodes (e.g., health.coredump) support only a single severity, thus only one subscription is required to subscribe to all available severities of this alert.

In order to unsubscribe recipients or addressees from a notification at a given severity level, delete the corresponding Subscription object. Or to remove only some endpoints, modify the object with the new set of recipient_ids and/or addressees (at least one recipient or addressee should remain on each Subscription object).

Filter property¶

This is an object selecting which alert events of the type named in notification_id should be delivered to the subscribed endpoints. For System Health alerts, two properties are used:

/notification_level - String, one of “HIGH”, “MEDIUM”, or “LOW”, corresponding to Health Severities “critical”, “major” and “minor”, respectively. Other string values are unsupported, will not allow alert subscriptions to be delivered, and may cause compatibility issues with the web UI. The subscribed receipient(s) and addressees will receive a notification when the triggered System Health Alert matches only this severity.

/notification_model - String. Must be “on_change”. Other values are unsupported.

Examples¶

Note

Creating subscriptions that are inconsistent with these examples may cause problems managing System Health alert subscriptions or Recipients through the AppResponse 11 web UI.

Subscriptions can be enumerated (note: this may be a very long list depending on how many subscriptions exist, not just to System Health Alerts, but also to Scheduled Reports and Policies):

--> GET /api/npm.usernotify/3.0/subscriptions
{
  "items": [
    ...
    {
      "notification_id": "health.coredump",
      "filter": {
        "/notification_level": "MEDIUM",
        "/notification_model": "on_change"
      },
      "recipient_ids": [
        1
      ],
      "id": 1,
      "addressees": []
    },
    ...
  ]
}

Subscriptions can be addressed and updated by their integer id. E.g., to change the subscribed severity level of a subscription to health.analysis_packet_drops from “critical” (“/notification_level”: “HIGH”) to “major” (“/notification_level”: “MEDIUM”):

--> GET /api/npm.usernotify/3.0/subscriptions/items/4
{
  "notification_id": "health.analysis_packet_drops",
  "filter": {
    "/notification_level": "HIGH",
    "/notification_model": "on_change"
  },
  "recipient_ids": [
    2,
    106
  ],
  "id": 4,
  "addressees": []
}
--> PUT /api/npm.usernotify/3.0/subscriptions/items/4
{
  "notification_id": "health.analysis_packet_drops",
  "filter": {
    "/notification_level": "MEDIUM",
    "/notification_model": "on_change"
  },
  "recipient_ids": [
    2,
    106
  ],
  "id": 4,
  "addressees": []
}
<-- 200 OK
...
Response body:
{
  "notification_id": "health.analysis_packet_drops",
  "filter": {
    "/notification_level": "MEDIUM",
    "/notification_model": "on_change"
  },
  "recipient_ids": [
    2,
    106
  ],
  "id": 4,
  "addressees": []
}

Note that after a change as above, if the System Health Alert Severity transitions from “major” to “critical”, a new alert will not be delivered. So in this case, to also add a subscription to the “critical” severity, create another Subscription object:

--> POST /api/npm.usernotify/3.0/subscriptions
{
  "notification_id": "health.analysis_packet_drops",
  "filter": {
    "/notification_level": "HIGH",
    "/notification_model": "on_change"
  },
  "recipient_ids": [
    2,
    106
  ],
  "addressees": ["critical-alerts@company.com"]
}
<-- 201 Created
...
Response body:
{
  "notification_id": "health.analysis_packet_drops",
  "filter": {
    "/notification_level": "HIGH",
    "/notification_model": "on_change"
  },
  "recipient_ids": [
    2,
    106
  ],
  "id": 5,
  "addressees": ["critical-alerts@company.com"]
}

In the case of health.coredump, which supports only a single severity, only one Subscription object needs to be created:

--> POST /api/npm.usernotify/3.0/subscriptions
{
"notification_id": "health.coredump",
"recipient_ids": [1],
"filter": {
    "/notification_level": "LOW",
    "/notification_model": "on_change"
  }
}
<-- 201 Created
...
Response body:
{
  "notification_id": "health.coredump",
  "filter": {
    "/notification_level": "LOW",
    "/notification_model": "on_change"
  },
  "recipient_ids": [
    1
  ],
  "id": 1,
  "addressees": []
}

Subscriptions can be deleted to stop receiving alert notifications. Subscriptions for the same alert to the same endpoints at lower severity levels should also be deleted, to maintain alerting consistency. The order of these deletions is not important.

--> GET /api/npm.usernotify/3.0/subscriptions/items/3
{
  "notification_id": "health.analysis_packet_drops",
  "filter": {
    "/notification_level": "MEDIUM",
    "/notification_model": "on_change"
  },
  "recipient_ids": [
    1
  ],
  "id": 1,
  "addressees": []
}
--> GET /api/npm.usernotify/3.0/subscriptions/items/5
{
  "notification_id": "health.analysis_packet_drops",
  "filter": {
    "/notification_level": "HIGH",
    "/notification_model": "on_change"
  },
  "recipient_ids": [
    1
  ],
  "id": 1,
  "addressees": []
}
--> DELETE /api/npm.usernotify/3.0/subscriptions/items/3
<-- 204 No Content
--> DELETE /api/npm.usernotify/3.0/subscriptions/items/5
<-- 204 No Content

Overview¶

Concepts for subscribing to System Health notifications¶

Introduction¶

Glossary¶

Delivery Type object¶

Example¶

Email Delivery Configuration¶

Example¶

Recipient object¶

Examples¶

Addressee objects¶

System Health Alert Notifications¶

Examples¶

Subscription objects¶

Filter property¶

Examples¶

Table Of Contents

This Page