RPC API Developer's Guide

Add a new Escalation Chain

Note that LogicMonitor has a REST API equivalent for this function.

Escalation Chains define the set of users who are notified at each stage of an alert's lifecycle.  An Escalation Chain consists of destination stages.  When an alert is routed to an escalation chain (via a matching alert rule) notifications are sent to the stages defined in the Escalation Chain. You can use the addEscalatingChain RPC to add new escalation chains programmatically.

Note: As with all our API calls, authentication is required.

 

addEscalatingChain

Add an Escalation Chain

URL:

https://accountName.logicmonitor.com/santaba/rpc/addEscalatingChain?c=accountName&u=user&p=password&name=escalationChainName&description=escalationChainDescription&enableThrottling=trueOrFalse&throttlingPeriod=10&throttlingAlerts=20&useTimeBased=trueOrFalse&destination=[{"type":"simple","stages":[[{"addr":"oncall0","method":"","comment":"","type":"group"}]]}]&ccdestination=[]

 

NOTE: The above URL has been URL-decoded for readability.

 

Request Parameters: You can include the following as query parameters in an addEscalatingChain request:

Parameter

Type

Description

name String Required. The unique name of the escalation chain.
description String Optional. The long text description of the escalation chain.
enableThrottling Boolean Optional. Enable/disable rate limiting of alerts sent to the recipients of this escalation chain. This value defaults to False.
throttlingAlerts Integer Required if enableThrottling is True. The number of alerts allowed during the specified period (throttlingPeriod). This value defaults to 20.
throttlingPeriod Integer Required if enableThrottling is True. The time period in minutes for throttling alerts. This value defaults to 10.
useTimeBased Boolean Optional. This value indicates whether the escalation chain should be a time-based escalation chain.
destination JSON String Optional. The primary destination for the escalation chain. This field must be a properly formatted JSON string containing one or more stages of recipients, and must be URL encoded. For help constructing this object, see the section below this table.
ccdestination JSON String Optional. The secondary destination for the escalation chain. This field must be a properly formatted JSON string containing one or more stages of recipients, and must be URL encoded. For help constructing this object, reference the section below this table.

Constructing the destination & ccdestination JSON objects

Note: This section assumes existing knowledge of JSON. If you are new to JSON please visit http://www.json.org/ before continuing.

Simple Escalation Chain Destination JSON Strings:

The JSON string for a non-timebased (simple) escalation chain requires the following values (Note: destination and ccdestination objects must be URL encoded in your request):

Parameter

Type

Description

type String The type of the escalation chain. For simple chains this value should be set to "simple".
stages JSON String A list of JSON string represented Stage objects. Each stage defined in the escalation chain must be a valid JSON string containing addr, method, comment, and type values.
addr String The name of either a user or a recipient group
method String If the addr references a user, this specifies the delivery method. Common values include "email" and "sms"
comment String Long text description of the stage
type String Either "admin" or "group" depending on the addr value. If the addr value is pointing to a user should be "admin". If pointing to a recipient group use "group".
 

------------- Sample Destination (URL decoded for readability) -------------
destination=[{"type":"simple","stages":[[{"addr":"oncall0","method":"","comment":"","type":"group"}]]}]
----------------------------------------------------------------------------
 

Time-Based Escalation Chain Destination JSON Strings:

The JSON string for a time-based escalation chain requires the following values (Note: this object must be URL encoded in your request):

Parameter

Type

Description

type String The type of the escalation chain. For timebased chains this value should be set to "timebased".
period JSON String A JSON representation of the days of the week and times of day that this escalation chain. e.g. {"weekdays":"1|2|3","start":0,"end":1440} for all day Sunday, Monday and Tuesday or {"weekdays":"1|2|3|4|5|6|7","start":360,"end":1050} for every day from 6:00 am to 5:30 pm
stages JSON String A list of JSON string represented Stage objects. Each stage defined in the escalation chain must be a valid JSON string containing addr, method, comment, and type values.
addr String The name of either a user or a recipient group
method String If the addr references a user, this specifies the delivery method. Common values include "email" and "sms"
comment String Long text description of the stage
type String Either "admin" or "group" depending on the addr value. If the addr value is pointing to a user should be "admin". If pointing to a recipient group use "group".
 

------------Sample Destination (URL decoded for readability) --------------
destination=[
{"type":"timebased","period":{"weekdays":"1|2|3","start":0,"end":1440},
"stages":[[{"addr":"oncall0","method":"","comment":"","type":"group"}]]},
{"type":"timebased","period":{"weekdays":"1|2|3|4|5|6|7","start":360,"end":1050},
"stages":[[{"addr":"oncall0","method":"","comment":"","type":"group"}]]}]
----------------------------------------------------------------------------
 

All outputs will be in the format: { [status], [data], [errmsg] }, where status is the status of the response, errmsg is the error message associated with the response, and the data object includes the following:

Value

Description

id The id number assigned to the newly created escalation chain
throttlingPeriod The time period for throttling alerts
throttlingAlerts The max number of alerts that will be sent in the throttlingPeriod
description The long text description
ccdestination The JSON string representing the cc recipients set for the escalation chain
name The name of the added escalation chain
enableThrottling The current state of alert throttling
inAlerting The current state of alerting on the escalation chain.
destination JSON string representing the set of stages including recipients

Example

Request:

curl "https://apiAccount.logicmonitor.com/santaba/rpc/addEscalatingChain?c=apiAccount&u=apiUser&p=example&name=MyEscalationChain&enableThrottling=false&destination=%5B%7B%22type%22%3A%22simple%22%2C%22stages%22%3A%5B%5B%7B%22addr%22%3A%22sarah%22%2C%22method%22%3A%22email%22%2C%22comment%22%3A%22%22%2C%22type%22%3A%22admin%22%7D%5D%2C%5B%7B%22addr%22%3A%22victoria%22%2C%22method%22%3A%22email%22%2C%22comment%22%3A%22%22%2C%22type%22%3A%22admin%22%7D%5D%5D%7D%5D" 
Response:

{
  "status": 200,
  "data": {
    "id": 19,
    "throttlingPeriod": 10,
    "throttlingAlerts": 20,
    "description": "",
    "ccdestination": [],
    "name": "MyEscalationChain",
    "enableThrottling": false,
    "inAlerting": false,
    "destination": [{
      "type": "simple",
      "stages": [
        [{
          "addr": "sarah",
          "method": "email",
          "comment": "",
          "type": "admin"
        }],
        [{
          "addr": "victoria",
          "method": "email",
          "comment": "",
          "type": "admin"
        }]
      ]
    }]
  },
  "errmsg": "OK"
}