Update alert escalation policy

URL

POST https://{api-url}/api/v2/tenants/{tenantId}/escalations/{id}

Sample URLs

https://{api-url}/api/v2/tenants/msp_5/escalations/POLICY-a0250f66-bf3a-7568-edef-83e7e8ac4231

https://{api-url}/api/v2/tenants/client_7/escalations/POLICY-e231dcc6-b338-466e-afc4-6638fc6de9a9

Parameters

Field	Sub-Fields	Data Type	Values	Description
name	NA	String	NA	(Optional) Escalation policy name.
description	NA	String	NA	(Optional) Escalation policy description.
resources	id type	String	NA Resource type DEVICE DEVICEGROUP SERVICEGROUP LOCATION CLIENT	(Optional) Resources on which the policy would be applied. Resource ID Resource type Example: DEVICE,Use the following APIs to fetch the resource types: Search Devices or Get Minimal Details of Resources API to fetch the list of devices or resources in a client. Get Child Device Groups and Get Root Level Device Groups to fetch the list of device groups. Get Service Groups to fetch the list of service groups. Search Sites to fetch the list of sites. Search Clients to fetch the list of clients. Only partner users have permission to fetch the details of client.
filterCriteria	1. matchingType	String	ALL, ANY	(Optional) Define alert conditions for the policy. Only the filtered alerts are escalated. All the alerts on the resource will match this policy if NO condition is defined. Match ANY or ALL of the filter rules.
	2. rules: Conditions to filter the alerts.
	1. key	String	Alert: Created Date Alert: Description Alert: Event Type Alert: Healed Time Alert: Metric Alert: No of Occurrence Alert: Source Alert: State Alert: Subject Alert: Type Alert: Update Time Resource: Aws Account Id Resource: Aws Instance Name Resource: Instance Id Resource: Resource IP Resource: Resource Name Resource: Resource Type	Unique attribute to filter the alert.Use Get Alert Types API to fetch the list of alert types.Alert: Occurrence Frequency: Escalate alerts which trigger repeatedly despite Acknowledge/Suppress actions. Below are the fields for alert occurrence frequency: occurrences Datatype: Integer Description: Rate at which an alert triggers repeatedly over a particular duration. Example: 5 frequency Data Type: Integer Description: Duration in which alert triggers repeatedly. Example: 2 frequencyType Data Type: String Description: Provide the type of duration.Supported values: hours, days, weeks. Example: days Consider a scenario where a user wants to escalate alerts which trigger repeatedly for 5 times in 2 days. For this scenario, the values are provided as "occurrences": 5 "frequency": 2 "frequencyType": "days"
	2. operator	String	Contains, Not Contains, Equals, Not Equals, Starts with, Ends with, Regex, Is	Operating values to filter the resource types. Operators Is and Is Not are applicable only for "key": "Resource: Resource Type"
	3. value	String	NA	Unique information of alert. Example: Critical. Example for filter rules: key: Alert: Subject, operator: Contains, value: Critical, this implies that filter the alerts that contain the subject critical.
escalationType	NA	String	MANUAL, AUTOMATIC	Escalation rules are actions to be taken when an alert is not acknowledged within the desired time. OpsRamp supports manual and automatic escalation types.
If escalation Type is Manual, then escalations would be:
escalations	recipients 1. id (or) name	String	NA	(Optional) Users to contact directly. User ID (or) name.
	2. type	String	USERS USER GROUPS ROSTERS USERGROUP_DL	User type. Use the following APIs to fetch the user types for the escalation: Search Users to fetch the list of users. Search User Groups to fetch the list of user groups. here to know more about User Group Distributed List. Provide only the user group IDs which have distributed list of email addresses configured in OpsRamp.
If escalation Type is Automatic, then escalations would be:
escalations	1. waitMins	Integer	0 to 30 mins, 45 mins 1 to 6 hours, 12 hours 1 day, 3 days, 5 days, 7 days, 10 days	Configure the time interval to escalate an alert after it is generated. Escalate after the alert has elapsed the set time. Convert hours and days to minutes and provide the minutes time format. Example: For 6 hours provide the value as 360 minutes.
	2. action	String	NOTIFICATION INCIDENT	Escalation action to be taken.Escalate as Notification implies to send periodic notifications to users until the alert is acknowledged. Escalate as Incident implies to automatically create an incident from the alert and assign it to the desired user or team.

NA indicates that the value is not applicable.

The table below has detailed information on escalation actions: Notification and Incident for escalation type Automatic.

Field	Sub-Fields	Data Type	Values	Description
escalationsaction: NOTIFICATION	recipients id (or) name type	String String	NA Recipient types: USER USER GROUPS ROSTERS USERGROUP_DL	Recipients who would receive the alert notifications. Recipient ID (or) name. Recipient type. Example: USERUse the following APIs to fetch the recipient types: Search Users to fetch the list of users. Search User Groups to fetch the list of user groups. Search Rosters to fetch the list of Rosters. User Group which has distributed list of email addresses. Click here to know more about User Group Distribution List. Provide only the user group IDs which have distributed list of email address configured in OpsRamp.
	2. priority	String	Very Low Low Normal High Urgent	Priority of the notification.
	3. repeatFrequency	Integer	5 mins, 10 mins, 15 mins, 20 mins, 30 mins, 1 hour, 2 hours, 3 hours, 4 hours, 6 hours, 8 hours, 12 hours, 24 hours	Repeat alert notification at specific time intervals. Example: If repeatFrequency is set as 15 minutes, then the alert notification would repeat every 15 minutes until the alert is acknowledged. Convert hours to minutes.
	4. notifyLimitCount	Integer	1 through 10	Number of repeated notifications a user has to receive within a certain time interval. For example, if repeatFrequency: 15 and notifyLimitCount: 5. The above example indicates that user receives notifications every 15 minutes and stops receiving after 5 notifications. When a notification limit count is not provided, the default notifyLimitCount is 2.
	5. alertStateTransitionFrom	String	CRITICAL, WARNING	Escalate alerts as notification on a change in alert state. For example, escalate alerts as notification when alert state changes from Warning to Critical. The notification is a one-time notification sent at the time of the state transition.
escalationsaction: INCIDENT	An Incident is automatically created from the alert and assigned to the desired user/team. Create New Incident Update Incident No further level of escalation can be added as the escalation will end when an incident is created from the alert.
	1. incident. Create New Incident: Configure the properties of an incident that will be created when an alert's condition matches with this policy.
	1. Assignee Group uniqueId name	String	NA	Escalate incident to a user group who would be responsible for working on the incident
	2. Assign id name	String	NA	Escalate incident to a user
	3. CustomFields id name value	String	NA	User customized fields. User can include additional information of incident by creating custom fields. Use Get Incident Custom Fields to get the custom forms of incident.
	4. businessImpact uniqueId	String	NA	The severity of an incident on the business. Use Get Business Impacts to get the list of defined business impacts.
	5. urgency uniqueId	String	NA	Urgency to prioritize and work on the incident. Use Get Urgencies to get the list of defined urgencies.
	6. Priority	String	Low, Normal, High, Urgent, Very Low	Priority of the incident. This can be defined with respect to business impact and urgency.
	7. Cc toEmail	String	NA	User would receive the incident notifications via email.
	2. updateIncident: Configure how to update an existing incident of an escalated alert. If an Open incident (other than Closed) is available for the alert, the incident gets updated instead of creating a new incident.
	none withAlertState (One of the above fields is mandatory.)	String	1. true, false 2. true, false	Update incident with respect to alert state. The latest description is appended on the alert. NO change to the status of the incident is made based on escalated alert's state. The incident gets updated every time the escalated alert repeats with a state change.
	3. priorityRules key operator value businessImpact uniqueId urgency uniqueId priority	String String String String String String	Value for key is [currentState.code]. Supported value for operator - Is. Supported values for the priority rule value are Warning, Critical. ID of the business impact. Urgency to prioritize the incident. Supported value for priority are Low, Normal, High, Urgent, Very Low.	3. Update incident priority based on these rules: Unique attribute of the alert. Example: Alert State Operating values to filter the incident. Example: Is Status of the incident. Example: Critical The severity of an incident on the business. Use Get Business Impacts to get the list of defined business impacts. Urgency to prioritize and work on the incident. Use Get Urgencies to get the list of defined urgencies. Priority of the incident. This can be defined with respect to business impact and urgency.
	4. notifyIncident forEveryUpdate whenAlertStateChanged (Either sub-field is mandatory)	String	NA	Notify users when incident is updated due to change in alert state.

Update alert escalation policy with automatic escalation

Sample request

{
	"name": "Network Devices Down",
	"description": "Issues in network devices.",
	"resources": [{
			"id": "bf3a10a2-92f1-4610-b3f4-174ed83db7b9",
			"type": "RESOURCE"
		},
		{
			"id": "DGP-0b165e70-7152-49f1-bfe3-ebe77409d5f2",
			"type": "DEVICEGROUP"
		},
		{
			"id": "SGP-11f1a6a8-acc8-411f-86c1-b693dd8e9817",
			"type": "SERVICEGROUP"
		},
		{
			"id": "7_AWS",
			"type": "LOCATION"
		},
		{
			"id": "client_7",
			"type": "CLIENT"
		}
	],
	"filterCriteria": {
		"matchingType": "ANY",
		"rules": [{
			"key": "Alert   : Description",
			"operator": "CONTAINS",
			"value": "critical"
		}, {
			"key": "Alert : Occurrence Frequency",
			"operator": "GREATERTHANOREQUALTO",
			"value": {
				"occurrences": "5",
				"frequency": "2",
				"frequencyType": "days"
			}
		}]
	},
	"escalationType": "AUTOMATIC",
	"escalations": [{
			"waitMins": 5,
			"priority": "Low",
			"repeatFrequency": 5,
			"action": "NOTIFICATION",
			"recipients": [{
					"id": "USR0000000028",
					"name": "AP_User",
					"type": "USER"
				},
				{
					"id": "USRGRP-9498fc95-67b7-3477-953f-1ec70bf0c61d",
					"name": "Cloud group",
					"type": "USERGROUP"
				},
				{
					"id": "ES-de9bfd9f-d8ee-430f-4bc0-e6e4645cdb47",
					"name": "Cloud roster",
					"type": "ROSTER"
				},
				{
					"id": "USRGRP-9498fc95-67b7-3477-953f-1ec70bf0c61d",
					"name": "OpsRamp group",
					"type": "USERGROUP_DL"
				}
			]
		},
		{
			"waitMins": 5,
			"action": "INCIDENT",
			"updateIncident": {
				"none": "true",
				"withAlertState": "true",
				"priorityRules": [{
					"key": "currentState.code",
					"operator": "Is",
					"value": "Warning",
					"businessImpact": {
						"uniqueId": "SIMPACT-e8853b21-ebc5-dd1d-d9a3-7a7b121a5e0f"
					},
					"urgency": {
						"uniqueId": "SURG-09358506-4af1-4d35-b902-cd3b14a00c10"
					},
					"priority": "High"
				}]
			},
			"notifyIncident": "whenAlertStateChanged",
			"incident": {
				"priority": "Very Low",
				"assigneeGroup": {
					"uniqueId": "USRGRP-4189ae2e-bcf5-f686-26d0-8b6eabd91558",
					"name": "Network Group"
				},
				"assignedUser": {
					"id": "USR0000000030",
					"loginName": "Ops_User"
				},
				"customFields": [{
						"id": "UDF0000000002",
						"name": "Number of attached incidents",
						"value": "2"
					},
					{
						"id": "UDF0000000004",
						"name": "Incident History",
						"value": "id": "UDF0000000004", "name": "esc_custom_field_4", "value": "$function.substring($alert.description ,'SITE ID=','\n')"
					}
				],
				"cc": "support@domain.com",
				"toEmail": "james.scott@domain.co"
			}
		}
	]
}

Sample response

{
	"id": "POLICY-e29f63f3-951a-4b41-a2a9-94835f6e9a42",
	"name": "Network Devices Down",
	"description": "Issue in Network devices.",
	"policyType": "ESCALATION_POLICY",
	"clientMatchingType": "ALL",
	"createdDate": "2017-05-15T10:35:51+0000",
	"updatedDate": "2017-05-15T10:35:51+0000",
	"active": true,
	"scope": {
		"id": 7,
		"uniqueId": "client_7",
		"name": "AB Client",
		"activated": true
	},
	"createdBy": {
		"loginName": "John.Smith",
		"lastName": "Smith",
		"firstName": "John",
		"email": "john.smith@domain.com"
	},
	"updatedBy": {
		"loginName": "vJohn.Smith",
		"lastName": "Smith",
		"firstName": "John",
		"email": "john.smith@domain.com"
	},
	"resources": [{
			"id": "bf3a10a2-92f1-4610-b3f4-174ed83db7b9",
			"name": "LPT00001",
			"type": "RESOURCE"
		},
		{
			"id": "7_AWS",
			"name": "AWS",
			"type": "LOCATION"
		},
		{
			"id": "DGP-0b165e70-7152-49f1-bfe3-ebe77409d5f2",
			"name": "Test Group",
			"type": "DEVICEGROUP"
		},
		{
			"id": "SGP-11f1a6a8-acc8-411f-86c1-b693dd8e9817",
			"name": "Test SG",
			"type": "SERVICEGROUP"
		},
		{
			"id": "client_6",
			"name": "OpsRamp Client",
			"type": "CLIENT"
		}
	],
	"filterCriteria": {
		"matchingType": "ALL",
		"rules": [{
			"key": "Alert   : Description",
			"operator": "CONTAINS",
			"value": "critical"
		}, {
			"key": "Alert : Occurrence Frequency",
			"operator": "GREATERTHANOREQUALTO",
			"value": {
				"occurrences": "5",
				"frequency": "2",
				"frequencyType": "days"
			}
		}]
	},
	"escalationType": "AUTOMATIC",
	"escalations": [{
			"waitMins": 5,
			"priority": "Low",
			"repeatFrequency": 5,
			"action": "NOTIFICATION",
			"recipients": [{
					"id": "USR0000000028",
					"name": "AP_User",
					"type": "USER"
				},
				{
					"id": "USRGRP-9498fc95-67b7-3477-953f-1ec70bf0c61d",
					"name": "Cloud group",
					"type": "USERGROUP"
				},
				{
					"id": "ES-de9bfd9f-d8ee-430f-4bc0-e6e4645cdb47",
					"name": "Cloud roster",
					"type": "ROSTER"
				},
				{
					"id": "USRGRP-9498fc95-67b7-3477-953f-1ec70bf0c61d",
					"name": "OpsRamp group",
					"type": "USERGROUP_DL"
				}
			]
		},
		{
			"waitMins": 5,
			"updateIncident": {
				"none": true,
				"priorityRules": [{
					"key": "currentState.code",
					"operator": "Is",
					"value": "Warning",
					"businessImpact": {
						"uniqueId": "SIMPACT-e8853b21-ebc5-dd1d-d9a3-7a7b121a5e0f",
						"name": "High Level Impact",
						"description": "The issue may cause fluctuations in network."
					},
					"urgency": {
						"uniqueId": "SURG-09358506-4af1-4d35-b902-cd3b14a00c10",
						"name": "High",
						"description": "Need to fix within 2 hours."
					},
					"priority": "High"
				}]
			},
			"incident": {
				"status": "New",
				"priority": "Low",
				"assignedUser": {
					"id": "USR0000000030",
					"loginName": "James.Rivers",
					"lastName": "Rivers",
					"firstName": "James",
					"email": "James.Rivers@domain.com",
					"phoneNumber": "",
					"mobileNumber": "406-559-1234"
				},
				"assigneeGroup": {
					"id": 1,
					"name": "Network Group",
					"description": "",
					"uniqueId": "USRGRP-4189ae2e-bcf5-f686-26d0-8b6eabd91558"
				},
				"customFields": [{
						"id": "UDF0000000002",
						"classCode": "INCIDENT",
						"displayLabel": "Number of attached incidents",
						"name": "Attached Incidents",
						"fieldType": "TYPE_TEXT",
						"mandatory": false,
						"editable": true,
						"description": "",
						"value": "2",
						"defaultValue": "",
						"customField": true
					},
					{
						"id": "UDF0000000004",
						"classCode": "INCIDENT",
						"displayLabel": "Incident History",
						"name": "Incident History",
						"fieldType": "TYPE_TEXT",
						"mandatory": false,
						"editable": true,
						"description": "",
						"value": "request custom field - text",
						"defaultValue": "",
						"customField": true
					}
				],
				"cc": "support@domain.com",
				"toEmail": "james.scott@domain.com"
			},
			"action": "INCIDENT",
			"notifyIncident": "whenAlertStateChanged"
		}
	]
}

Update alert escalation policy with manual escalation

Sample request

{

	"id": "POLICY-a204aea2-f943-46cb-86fa-86197e796f70",
	"name": "Network Devices Down",
	"description": "Issues in network devices.",
	"policyType": "ESCALATION_POLICY",
	"clientMatchingType": "ALL",
	"createdDate": "2017-05-15T11:10:32+0000",
	"updatedDate": "2017-05-15T11:10:32+0000",
	"active": true,
	"scope": {
		"id": 5,
		"uniqueId": "msp_5",
		"name": "OpsRamp Partner",
		"activated": true
	},
	"createdBy": {
		"loginName": "John.Smith",
		"lastName": "Smith",
		"firstName": "John",
		"email": "john.smith@domain.com"
	},
	"updatedBy": {
		"loginName": "John.Smith",
		"lastName": "Smith",
		"firstName": "John",
		"email": "john.smith@domain.com"
	},
	"resources": [{
			"id": "bf3a10a2-92f1-4610-b3f4-174ed83db7b9",
			"name": "LPT00001",
			"type": "RESOURCE"
		},
		{
			"id": "7_AWS",
			"name": "AWS",
			"type": "LOCATION"
		},
		{
			"id": "DGP-0b165e70-7152-49f1-bfe3-ebe77409d5f2",
			"name": "Network Group",
			"type": "DEVICEGROUP"
		},
		{
			"id": "SGP-11f1a6a8-acc8-411f-86c1-b693dd8e9817",
			"name": "Network Service Group",
			"type": "SERVICEGROUP"
		},
		{
			"id": "client_6",
			"name": "OpsRamp Client",
			"type": "CLIENT"
		}
	],
	"filterCriteria": {
		"matchingType": "ALL",
		"rules": [{
			"key": "Alert  : Description",
			"operator": "CONTAINS",
			"value": "critical"
		}]
	},
	"escalationType": "MANUAL",
	"escalations": [{
		"action": "NOTIFICATION",
		"recipients": [{
				"id": "USR0000000019",
				"name": "Partner.A",
				"type": "USER"
			},
			{
				"id": "USRGRP-9498fc95-67b7-3477-953f-1ec70bf0c61d",
				"name": "Cloud group",
				"type": "USERGROUP"
			},
			{
				"id": "ES-d16473ee-29de-1cf2-4983-86307733e34c",
				"name": "Test roster",
				"type": "ROSTER"
			}
		]
	}]
}

Sample response

{

	"id": "POLICY-a204aea2-f943-46cb-86fa-86197e796f70",
	"name": "Network Devices Down",
	"description": "Issues in network devices.",
	"policyType": "ESCALATION_POLICY",
	"clientMatchingType": "ALL",
	"createdDate": "2017-05-15T11:10:32+0000",
	"updatedDate": "2017-05-15T11:10:32+0000",
	"active": true,
	"scope": {
		"id": 5,
		"uniqueId": "msp_5",
		"name": "OpsRamp Partner",
		"activated": true
	},
	"createdBy": {
		"loginName": "John.Smith",
		"lastName": "Smith",
		"firstName": "John",
		"email": "john.smith@domain.com"
	},
	"updatedBy": {
		"loginName": "John.Smith",
		"lastName": "Smith",
		"firstName": "John",
		"email": "john.smith@domain.com"
	},
	"resources": [{
			"id": "bf3a10a2-92f1-4610-b3f4-174ed83db7b9",
			"name": "LPT00001",
			"type": "RESOURCE"
		},
		{
			"id": "7_AWS",
			"name": "AWS",
			"type": "LOCATION"
		},
		{
			"id": "DGP-0b165e70-7152-49f1-bfe3-ebe77409d5f2",
			"name": "Network Group",
			"type": "DEVICEGROUP"
		},
		{
			"id": "SGP-11f1a6a8-acc8-411f-86c1-b693dd8e9817",
			"name": "Network Service Group",
			"type": "SERVICEGROUP"
		},
		{
			"id": "client_6",
			"name": "OpsRamp Client",
			"type": "CLIENT"
		}
	],
	"filterCriteria": {
		"matchingType": "ALL",
		"rules": [{
			"key": "Alert  : Description",
			"operator": "CONTAINS",
			"value": "critical"
		}]
	},
	"escalationType": "MANUAL",
	"escalations": [{
		"action": "NOTIFICATION",
		"recipients": [{
				"id": "USR0000000019",
				"name": "Partner.A",
				"type": "USER"
			},
			{
				"id": "USRGRP-9498fc95-67b7-3477-953f-1ec70bf0c61d",
				"name": "Cloud group",
				"type": "USERGROUP"
			},
			{
				"id": "ES-d16473ee-29de-1cf2-4983-86307733e34c",
				"name": "Test roster",
				"type": "ROSTER"
			}
		]
	}]
}