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, Zenoss Cloud sends a message to all the destinations in the rule.

Only rules can initiate actions.

Resource list

Create a rule (POST /v1/notification/rules)
Get one rule (GET /v1/notification/rules/{name})
Get all or multiple rules (GET /v1/notification/rules[?query])
Update a rule (PUT /v1/notification/rules/{name})
Delete a rule (DELETE /v1/notification/rules/{name})

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

name (string, required)

A unique, short identifier for the rule.

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

description (string, optional)

Additional text to further describe the rule.

enabled (boolean, optional, default = false)

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

triggerNames (array, optional)

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

destinationNames (array, optional)

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

message (string, optional)

The text to send to destinations. Templates are supported.

repeat (boolean, optional, default = false)

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

repeatInterval (string, optional)

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, optional, default = false)

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.

tags (array, optional)

A list of arbitrary terms to associate with the rule.

Status codes

200 (OK: rule was created)
400 (Bad Request: invalid rule)
409 (Conflict: a rule with the same name already exists)

Example

RequestResponse

cat << EOF | 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"]
}
EOF

{
  "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

200 (OK: rule exists)
404 (Not Found: rule doesn't exist)

Example

RequestResponse

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

{
  "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.

recentNotificationCount: The total number of notifications sent in the last 24 hours that used a rule, if any.
totalCount: The total number of rules returned.

Status Codes

200 (OK)

All rules example

RequestResponse

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

{
  "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

RequestResponse

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

{
  "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

200 (OK: rule was updated)
400 (Bad Request: invalid rule)
404 (Not Found: rule doesn't exist)

Example

RequestResponse

cat << EOF | 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"]
}
EOF

{
  "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

200 (OK: rule was deleted)
404 (Not Found: rule doesn't exist)

Example

RequestResponse

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

{}