URL

POST https://{api-url}/api/v2/tenants/{tenantId}/policies/alertCorrelation/{policyId}

Sample URLs

https://{api-url}/api/v2/tenants/client_7/policies/alertCorrelation/POLICY-AC-3218d82f-25c6-4d4d-bd88-b83c5e30721c
https://{api-url}/api/v2/tenants/msp_6/policies/alertCorrelation/POLICY-AC-ce200249-bcb0-47ef-8b24-9b5744053243

Parameters

FieldData TypeValuesDescription
"name"StringNAThe name of the alert correlation policy.
"filterCriteria"String(Optional) Filter for resources whose alerts will match this policy.
  • "filterBased"
Boolean"true" or "false"Determine if the alert correlation policy should consider the below filter rules.
  • "matchingType"
Boolean"ALL" or "ANY"Match ALL or ANY of the rules to filter for resources whose alerts will match this policy.
  • "rules"
(Mandatory if "filterBase": "true") Filter resources with the rules that follow.
    • "filterType"
String"nativeAttributes"
"customAttributes"		Filter for resources on the basis of predefined attributes.
Filter for resources using custom attributes of device and client.
    • "entityName"
StringEntity names of native attributes:
  • "dns_name"
  • "host_name"
  • "alias_name"
  • "ip_address"
  • "agent_installed"
  • "operating_system"
  • "make"
  • "model"
  • "alert_source"
  • "alert_metric"
For more options, view Get Custom Attributes of a Client API.		Native or custom attribute name. For example, to filter for resources with host_name "VG-Host", use the following:
"filterType":"nativeAttributes",
"entityName":"host_name",
"operator":"CONTAINS",
"entityValue":"VG-Host"

To filter for resources with a custom attribute"Agent Status", use the following:
"filterType":"customAttributes",
"entityName":"Agent Status",
"operator":"CONTAINS",
"entityValue":"Up"
    • "operator"
String
  • "Contains"
  • "Not Contains"
  • "Equals"
  • "Not Equals"
  • "Starts with"
  • "Ends with"
  • "Regex"
  • "Is"
The logical operators to filter for resources. To filter Windows resources, use "Contains Windows". To filter resources with the agent is installed, use the following:
"entityName": "agent_installed",
"operator": "Is",
"entityValue": "Yes"

View to learn more about how to form regular expressions.
    • "entityValue"
StringNAThe unique value of the alert. An example would be "VG-Host".
    • "ipMatchingConditions"
Object
"type"String"DEPENDENCY"
"ALGORITHM"
"CO_OCCURRENCE"
The alert correlation policy type.
"dependencyCorrelation"StringCorrelate alerts on upstream and downstream resources. See the Create Alert Correlation Policy API to learn more about creating a dependency correlation.
  • "alertsTimeWindow"
Integer5, 10, 15, 20, 25, 30, 45, 60, 90, 120(Optional) Correlate alerts that are generated within a time span specified in minutes. An example is when a user wants to correlate alerts on upstream and downstream resources within a span of 15 minutes. If a value isn't specified, the default time window is 5 minutes.
  • "upstreamMetrics"
ListNAMetrics on the upstream resource that may generate alerts. Use the Get Metrics API to retrieve metrics assigned to a resource.
  • "downstreamMetrics"
ListNAMetrics on the downstream resource that may generate alerts. Use the Get Metrics API to retrieve metrics assigned to a resource.
"algorithmCorrelation"StringCorrelate alerts that share similar alert properties.
  • "alertsTimeWindow"
Integer5, 10, 15, 20, 25, 30, 45, 60, 90, 120(Optional) Correlate alerts that are generated within a time span specified in minutes. If a value isn't specified, the default time window is 5 minutes.
  • "matchingConditions"
    • "property"
    • "matchType"
  • "List"
    • "String"
    • "String"
  • Valid "property" values:
    • "resource_type"
    • "subject"
    • "host_name"
    • "alert_source"
    • "alert_metric"
  • Valid "matchType" values:
    • "Identical"
    • "Nearly Identical"
    • "Similar"
    • "Somewhat"
Correlate alerts based all of the on the following:
  1. Select the alert property with which the alerts should be grouped (example is "Host Name").
  2. Match the type of alert property.
For example, a user wants to correlate alerts which exactly share similar Host Name, then provide "property": "host_name", "matchType": "Identical"
  • "primaryAlertSubject"
StringNA(Optional) Provide a subject for the primary alert generated. This helps to identify the Inference. If no subject is provided, the primary alert is treated as the subject for alert correlation.
"enabledMode"String"ON"
"OFF"
"OBSERVED"
(Optional) To enable an alert correlation policy, set "enabledMode": "ON". To disable an alert correlation policy, set "enabledMode: "OFF". To enable an alert correlation policy to observe, set "enabledMode": "OBSERVED".
"precedence"IntegerNA(Optional) Determine the execution order of a policy. For example, if VMware is part of agent status policy and network outage policy, the user can determine which policy should execute first to correlate VMware alerts.
  • "machineLearning"
    • "trainingFileId"
    • "continuousLearning"
Client Scope Partner Policy
  • "organizationMatchingType"
  • "includedClients"
"precedence"IntegerNA(Optional) Determine the execution order of a policy. For example, if VMware is specified as part of the agent status policy and network outage policy, the user can determine which policy should execute first to correlate VMware alerts.

NA indicates that the value is not applicable.

Update alert correlation policy with dependency correlation

Sample request

{
	"name": "Correlate alerts on Hypervisor",
	"enabled": "false",
	"precedence": 25,
	"filterCriteria": {
		"filterBased": "true",
		"matchingType": "ALL",
		"rules": [{
				"filterType": "nativeAttributes",
				"entityName": "host_name",
				"operator": "Contains",
				"entityValue": "vm"
			},
			{
				"filterType": "customAttributes",
				"entityName": "Root_Device",
				"operator": "Starts with",
				"entityValue": "ESX"
			}
		]
	},
	"type": "DEPENDENCY",
	"dependencyCorrelation": {
		"alertsTimeWindow": "15",
		"upstreamMetrics": [
			"system.ping.pl",
			"system.process.cpu"
		],
		"downstreamMetrics": [
			"system.ping.rta",
			"system.memory.utilization"
		]
	}
}

Sample response

{
	"id": "POLICY-AC-165c4ee5-8b31-4cba-b88e-f20e57ae8358",
	"name": "Correlate alerts on Hypervisor",
	"enabled": false,
	"precedence": 25,
	"filterCriteria": {
		"filterBased": true,
		"matchingType": "ALL",
		"rules": [{
			"filterType": "nativeAttributes",
			"entityName": "host_name",
			"operator": "Contains",
			"entityValue": "vm"
		}, {
			"filterType": "customAttributes",
			"entityName": "Root_Device",
			"operator": "Starts with",
			"entityValue": "ESX"
		}]
	},
	"type": "DEPENDENCY",
	"dependencyCorrelation": {
		"alertsTimeWindow": 15,
		"upstreamMetrics": ["system.process.cpu", "system.ping.pl"],
		"downstreamMetrics": ["system.memory.utilization", "system.ping.rta"]
	},
	"createdBy": {
		"loginName": "John_Smith",
		"lastName": "Smith",
		"firstName": "John",
		"email": "john.smith@myorganization.com"
	},
	"updatedBy": {
		"loginName": "John_Smith",
		"lastName": "Smith",
		"firstName": "John",
		"email": "john.smith@myorganization.com"
	},
	"createdTime": "2018-03-27T13:14:07+0000",
	"updatedTime": "2018-04-10T14:22:10+0000"
}

Create alert correlation policy with algorithm-based correlation

Sample request

{
	"name": "Correlate alerts on network outage",
	"enabled": "false",
	"filterCriteria": {
		"filterBased": "true",
		"matchingType": "ALL",
		"rules": [{
				"filterType": "nativeAttributes",
				"entityName": "ip_address",
				"operator": "Contains",
				"entityValue": "162.11"
			},
			{
				"filterType": "customAttributes",
				"entityName": "device_location",
				"operator": "Regex",
				"entityValue": "*West"
			}
		]
	},
	"type": "ALGORITHM",
	"algorithmCorrelation": {
		"alertsTimeWindow": "20",
		"matchingConditions": [{
				"property": "subject",
				"matchType": "Identical"
			},
			{
				"property": "ip_address",
				"matchType": "Nearly Identical"
			}
		],
		"primaryAlertSubject": "Network outage on Switch 162"
	}
}

Sample response

{
	"id": "POLICY-AC-7556bcf6-4cc2-44ba-ba1f-3ca5a211bcb3",
	"name": "Correlate alerts on network outage",
	"enabled": false,
	"precedence": 29,
	"filterCriteria": {
		"filterBased": true,
		"matchingType": "ALL",
		"rules": [{
			"filterType": "nativeAttributes",
			"entityName": "ip_address",
			"operator": "CONTAINS",
			"entityValue": "162.11"
		}, {
			"filterType": "customAttributes",
			"entityName": "device_location",
			"operator": "Regex",
			"entityValue": "*West"
		}]
	},
	"type": "ALGORITHM",
	"algorithmCorrelation": {
		"alertsTimeWindow": 20,
		"matchingConditions": [{
			"property": "subject",
			"matchType": "Identical"
		}, {
			"property": "ip_address",
			"matchType": "Nearly Identical"
		}],
		"primaryAlertSubject": "Network outage on Switch 162 "
	},
	"createdBy": {
		"loginName": "John_Smith",
		"lastName": "Smith",
		"firstName": "John",
		"email": "john.smith@myorganization.com"
	},
	"updatedBy": {
		"loginName": "John_Smith",
		"lastName": "Smith",
		"firstName": "John",
		"email": "john.smith@myorganization.com"
	},
	"createdTime": "2018-03-27T13:14:07+0000",
	"updatedTime": "2018-04-10T14:22:11+0000"
}

Create Alert Correlation Policy with Cooccurrence-Based Correlation

Sample request

{
	"name": "Server-SJ Alerts",
	"filterCriteria": {
		"filterBased": "true",
		"matchingType": "ALL",
		"rules": [{
				"filterType": "nativeAttributes",
				"entityName": "host_name",
				"operator": "Contains",
				"entityValue": "Logix"
			},
			{
				"filterType": "customAttributes",
				"entityName": "device_location",
				"operator": "Contains",
				"entityValue": "West-SJ"
			}
		]
	},
	"type": "CO_OCCURRENCE"
}

Sample response

{
	"id": "POLICY-AC-7556bcf6-4cc2-44ba-ba1f-3ca5a211bcb3",
	"name": "Server-SJ Alerts",
	"enabled": true,
	"precedence": 30,
	"filterCriteria": {
		"filterBased": true,
		"matchingType": "ALL",
		"rules": [{
			"filterType": "nativeAttributes",
			"entityName": "host_name",
			"operator": "Contains",
			"entityValue": "Logix"
		}, {
			"filterType": "customAttributes",
			"entityName": "device_location",
			"operator": "Contains",
			"entityValue": "West-SJ"
		}]
	},
	"type": "CO_OCCURRENCE",
	"createdBy": {
		"loginName": "opsramp_api_user",
		"lastName": " ",
		"firstName": "OpsRamp API User",
		"email": "john.smith@myorganization.com"
	},
	"updatedBy": {
		"loginName": "opsramp_api_user",
		"lastName": " ",
		"firstName": "OpsRamp API User",
		"email": "john.smith@myorganization.com"
	},
	"createdTime": "2018-08-27T13:14:07+0000",
	"updatedTime": "2018-09-10T11:10:20+0000"
}

Create Alert Correlation Policy with IP address filter

Sample request

{
   "name":"IP policy api demo",
   "type":"ALGORITHM",
   "filterCriteria": {
	"filterBased":"true",
	"matchingType":"ALL",
	"rules":
	[
	  {
		"filterType":"nativeAttributes",
		"entityName":"ip_address",
		"ipMatchingConditions": {
			"ipAddressMatchType":"CIDR Match",
			"cidrNotation":"192.168.1.1/24"
			}
		}
	]
   },
   "algorithmCorrelation": {
	"alertsTimeWindow":"20",
	"matchingConditions":[
	{
		"property":"host_name",
		"matchType":"Identical"
	}
	],
	"primaryAlertSubject":"IP policy api demo"
   }
}

Sample response

{
    "id": "POLICY-AC-498fe534-f70b-4511-80cd-88138ab15122",
    "name": "IP policy api demo",
    "enabled": true,
    "precedence": 87,
    "filterCriteria": {
        "filterBased": true,
        "matchingType": "ALL",
        "rules": [
            {
                "filterType": "nativeAttributes",
                "entityName": "ip_address",
                "ipMatchingConditions": {
                    "ipAddressMatchType": "CIDR Match",
                    "cidrNotation": "192.168.1.1/24"
                }
            }
        ]
    },
    "type": "ALGORITHM",
    "algorithmCorrelation": {
        "alertsTimeWindow": 20,
        "matchingConditions": [
            {
                "property": "host_name",
                "matchType": "Identical"
            }
        ],
        "primaryAlertSubject": "IP policy api demo"
    },
    "createdBy": {
        "loginName": "opsramp_api_user",
        "lastName": " ",
        "firstName": "OpsRamp API User",
        "email": "admin@opsramp.com"
    },
    "createdTime": "2018-12-28T10:37:32+0000",
    "updatedTime": ""
}

Create client scope partner alert correlation policy correlated with algorithm and ALL based on organizationMatchingType

Sample request

{
   "name":"test_algorithm_correlation_ap",
   "organizationMatchingType":"ALL",
   "filterCriteria": {
	"filterBased":"true",
	"matchingType":"ALL",
	"rules":
	[
		{
			"filterType":"nativeAttributes",
			"entityName":"host_name",
			"operator":"Contains",
			"entityValue":"vm"
		},
		{
			"filterType":"customAttributes",
			"entityName":"test_custom_attribute",
			"operator":"Not Contains",
			"entityValue":"a"
		}
	]
   },
   "type":"ALGORITHM",
   "algorithmCorrelation": {
	"alertsTimeWindow":"20",
	"matchingConditions":[
	{
		"property":"subject",
		"matchType":"Identical"
	},
	{
		"property":"alert_metric",
		"matchType":"Identical"
	}
	],
	"primaryAlertSubject":"subject-alertMetric policy"
}
}

Sample response

{
  "id" : "POLICY-AC-7556bcf6-4cc2-44ba-ba1f-3ca5a211bcb3",
  "name" : "test_algorithm_correlation_ap",
  "clientsIncluded" : "ALL",
  "enabled" : true,
  "precedence" : 29,
  "filterCriteria" : {
       "filterBased" : true,
       "matchingType" : "ALL",
       "rules" : [ {
          "filterType" : "nativeAttributes",
          "entityName" : "host_name",
          "operator" : "Contains",
          "entityValue" : "vm"
    }, {
          "filterType" : "customAttributes",
          "entityName" : "test_custom_attribute",
          "operator" : "Not Contains",
          "entityValue" : "a"
    } ]
  },
     "type":"ALGORITHM",
     "algorithmCorrelation" : {
        "alertsTimeWindow" : 20,
        "matchingConditions" : [ {
               "property" : "subject",
               "matchType" : "Identical"
         }, {
               "property" : "alert_metric",
               "matchType" : "Identical"
         } ],
         "primaryAlertSubject" : "subject-alertMetric policy"
    },
  "createdBy" : {
    "loginName" : "opsramp_api_user",
    "lastName" : " ",
    "firstName" : "OpsRamp API User",
    "email" : "admin@opsramp.com"
  },
  "createdTime" : "2017-11-27T13:14:07+0000",
  "updatedTime" : ""
}

Create client scope partner alert correlation policy correlated with algorithm and INCLUDE based on organizationMatchingType

Sample request

{
"name":"test_algorithm_correlation_ap",
"organizationMatchingType":"INCLUDE",
"includedClients":[
"client_8",
"client_9"],
"filterCriteria": {
	"filterBased":"true",
	"matchingType":"ALL",
	"rules":
	[
		{
			"filterType":"nativeAttributes",
			"entityName":"host_name",
			"operator":"Contains",
			"entityValue":"vm"
		},
		{
			"filterType":"customAttributes",
			"entityName":"test_custom_attribute",
			"operator":"Not Contains",
			"entityValue":"a"
		}
	]
},
"type":"ALGORITHM",
"algorithmCorrelation": {
	"alertsTimeWindow":"20",
	"matchingConditions":[
	{
		"property":"subject",
		"matchType":"Identical"
	},
	{
		"property":"alert_metric",
		"matchType":"Identical"
	}
	],
	"primaryAlertSubject":"subject-alertMetric policy"
}
}

Sample response

{
  "id" : "POLICY-AC-7556bcf6-4cc2-44ba-ba1f-3ca5a211bcb3",
  "name" : "test_algorithm_correlation_ap",
  "includedClients":[
   "client_8",
   "client_9"],
  "enabled" : true,
  "precedence" : 29,
  "filterCriteria" : {
    "filterBased" : true,
    "matchingType" : "ALL",
    "rules" : [ {
      "filterType" : "nativeAttributes",
      "entityName" : "host_name",
      "operator" : "Contains",
      "entityValue" : "vm"
    }, {
      "filterType" : "customAttributes",
      "entityName" : "test_custom_attribute",
      "operator" : "Not Contains",
      "entityValue" : "a"
    } ]
  },
  "type":"ALGORITHM",
  "algorithmCorrelation" : {
    "alertsTimeWindow" : 20,
    "matchingConditions" : [ {
      "property" : "subject",
      "matchType" : "Identical"
    }, {
      "property" : "alert_metric",
      "matchType" : "Identical"
    } ],
    "primaryAlertSubject" : "subject-alertMetric policy"
  },
  "createdBy" : {
    "loginName" : "opsramp_api_user",
    "lastName" : " ",
    "firstName" : "OpsRamp API User",
    "email" : "admin@opsramp.com"
  },
  "createdTime" : "2017-11-27T13:14:07+0000",
  "updatedTime" : ""
}