Skip to main content

Rule resources

A rule combines one or more triggers with one or more destinations and a customized message. When conditions match any trigger in a rule, Virtana Service Observability sends a message to all the destinations in the rule.

Only rules can initiate actions.

Resource list

POST /v1/notification/rules

Create a rule.

Request template

An abstract preview of a JSON request to create one rule.

{
  "name": "<rule-name>",
  "description": "<description>",
  "enabled": <boolean>,
  "triggerNames": [ "<triger-name>" ],
  "destinationNames": [ "<destination-name>" ],
  "message": "<message>",
  "repeat": <boolean>,
  "repeatInterval": <seconds>,
  "sendUpdates": <boolean>,
  "tags": [ "<tag>" ]
}

Request fields

Field

Type

Required

Description

name

String

Yes

A unique, short identifier for the rule.

Once created, the value of a name field cannot be changed.

description

String

No

Additional text to further describe the rule.

destinationNames

Array

No

A list of strings (destination names) to associate with the rule.

enabled

Boolean

No

The state of the rule, enabled (true) or disabled (false). Default: false.

message

String

No

The text to send to destinations. Template are supported.

repeat

Boolean

No

Repeat the action (send notifications) each time a trigger matches. Default: false.

repeatInterval

String

No

The amount of time to wait before repeating the action (send notifications), in seconds. Only in effect when repeat is true.

To ensure that notifications for all matching triggers are sent, set the value of this field to zero. Actions for matching triggers are suppressed until this interval elapses. The default value is 3600 seconds (1 hour).

sendUpdates

Boolean

No

Perform the action (send notifications) when the conditions that previously matched a trigger change significantly. For example, when an event is closed, acknowledged, or changes severity. Default: false.

tags

Array

No

A list of arbitrary terms to associate with the rule.

triggerNames

Array

No

A list of strings (trigger names) to associate with the rule.

Status codes

Code

Description

200

Success. The request was processed. Check the response body for per-item results when processing multiple objects.

400

Bad request. The request body is missing, malformed, or contains invalid values.

409

Conflict. A resource with the same name already exists.

Example

Request example

 curl https://YOUR-API-ENDPOINT/v1/notification/rules \
  -H "zenoss-api-key: $ZENOSS_API_KEY" -X POST -s -d @-
{
    "name": "rule-1",
    "description": "Rule combining trigger-1 with destination-1.",
    "enabled": true,
    "triggerNames": ["trigger-1"],
    "destinationNames": ["destination-1"],
    "message": "This is that notification you wanted.",
    "repeat": true,
    "repeatInterval": 3600,
    "sendUpdates": true,
    "tags": ["example"]
}

Response example

 {
  "rule": {
    "name": "rule-1",
    "description": "Rule combining trigger-1 with destination-1.",
    "triggerNames": [
      "trigger-1"
    ],
    "destinationNames": [
      "destination-1"
    ],
    "message": "This is that notification you wanted.",
    "enabled": true,
    "repeat": true,
    "repeatInterval": "3600",
    "sendUpdates": true,
    "tags": [
      "example"
    ]
  }
}

GET /v1/notification/rules/{name}

Get one rule.

Status codes

Code

Description

200

Success. The request was processed. Check the response body for per-item results when processing multiple objects.

404

Not found. The specified resource does not exist.

Example

Request example

curl https://YOUR-API-ENDPOINT/v1/notification/rules/YOUR-RULE-NAME \
  -H "zenoss-api-key: YOUR-API-KEY" -X GET -s

Response example

{
  "rule": {
    "name": "YOUR-RULE-NAME",
    "description": "Rule combining trigger-1 with destination-1.",
    "triggerNames": [
      "trigger-1"
    ],
    "destinationNames": [
      "destination-1"
    ],
    "message": "This is that notification you wanted.",
    "enabled": true,
    "repeat": true,
    "repeatInterval": "3600",
    "sendUpdates": true,
    "tags": [
      "example"
    ]
  }
}

GET /v1/notification/rules[?query]

Get all rules or rules that match a query. Requests with no queries will return all rules.

Queries may be appended to the base URL with standard query syntax. See the query string example.

Query fields

Field

Value

Comparison

Repeat?

name

String

Contains

No (may be used only once)

description

String

Contains

No

enabled

Boolean

Equal to

No

triggerNames

String

Contains

Yes (may be used multiple times)

destinationNames

String

Contains

Yes

message

String

Contains

No

repeat

Boolean

Equal to

No

repeatInterval

Number

Equal to

No

sendUpdates

Boolean

Equal to

No

tags

String

Contains

Yes

For more information about query fields, see the create a rule resource.

Response fields

Responses may include the following fields.

Field

Description

recentNotificationCount

 

totalCount

 

Status codes

Code

Description

200

Success. The request was processed. Check the response body for per-item results when processing multiple objects.

All rules example

Request

curl https://YOUR-API-ENDPOINT/v1/notification/rules \
  -H "zenoss-api-key: YOUR-API-KEY" -X GET -s

Response

{
  "rules": [
    {
      "name": "rule-1",
      "description": "Rule combining trigger-1 with destination-1.",
      "triggerNames": [
        "trigger-1"
      ],
      "destinationNames": [
        "destination-1"
      ],
      "message": "This is that notification you wanted.",
      "enabled": false,
      "repeat": true,
      "repeatInterval": "3600",
      "sendUpdates": true,
      "tags": [
        "example"
      ]
    }
  ],
  "totalCount": "1"
}

Query string example

Request example

curl https://YOUR-API-ENDPOINT/v1/notification/rules?enabled=false&repeat=true \
  -H "zenoss-api-key: YOUR-API-KEY" -X GET -s

Response example

{
  "rules": [
    {
      "name": "rule-1",
      "description": "Rule combining trigger-1 with destination-1.",
      "triggerNames": [
        "trigger-1"
      ],
      "destinationNames": [
        "destination-1"
      ],
      "message": "This is that notification you wanted.",
      "enabled": false,
      "repeat": true,
      "repeatInterval": "3600",
      "sendUpdates": true,
      "tags": [
        "example"
      ]
    }
  ],
  "totalCount": "1"
}

PUT /v1/notification/rules/{name}

Update an existing rule.

Rule names cannot be changed.

Request fields

Update requests use the same fields as create requests.

Status codes

Code

Description

200

Success. The request was processed. Check the response body for per-item results when processing multiple objects.

400

Bad request. The request body is missing, malformed, or contains invalid values.

404

Not found. The specified resource does not exist.

Example

Request example

 curl https://YOUR-API-ENDPOINT/v1/notification/rules/YOUR-RULE-NAME \
    -H "zenoss-api-key: YOUR-API-KEY" -X PUT -s -d @-
{
    "description": "Updated rule combining trigger-1 with destination-1.",
    "enabled": true,
    "triggerNames": ["trigger-1"],
    "destinationNames": ["destination-1"],
    "message": "This is that updated notification you wanted.",
    "repeat": true,
    "repeatInterval": 3600,
    "sendUpdates": true,
    "tags": ["example"]
}

Response example

{
  "rule": {
    "name": "YOUR-RULE-NAME",
    "description": "Updated rule combining trigger-1 with destination-1.",
    "triggerNames": [
      "trigger-1"
    ],
    "destinationNames": [
      "destination-1"
    ],
    "message": "This is that updated notification you wanted.",
    "enabled": true,
    "repeat": true,
    "repeatInterval": "3600",
    "sendUpdates": true,
    "tags": [
      "example"
    ]
  }
}

DELETE /v1/notification/rules/{name}

Delete a rule.

Status codes

Code

Description

200

Success. The request was processed. Check the response body for per-item results when processing multiple objects.

404

Not found. The specified resource does not exist.

Example

Request example

curl https://YOUR-API-ENDPOINT/v1/notification/rules/YOUR-RULE-NAME \ -H "zenoss-api-key: YOUR-API-KEY" -X DELETE -s

Response example

{}
In this section: