Create alert correlation policy

This endpoint is used to create an alert correlation policy.

Leave Feedback

URL

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

Sample URLs

https://{api-url}/api/v2/tenants/client_7/policies/alertCorrelation
https://{api-url}/api/v2/tenants/msp_6/policies/alertCorrelation

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"
  • "resource_type"
  • "agent_installed"
  • "operating_system"
  • "make"
  • "model"
  • "alert_source"
  • "alert_metric"
  • "device_group"
  • "service_group"
  • "site"
  • "application"
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"
String
  • "CIDR Match"
  • "Within Range"
  • "Equals"
    • Mandatory
    • Mandatory only when "CIDR Match" is selected. (An example is "192.168.1.1/24".)
    • Mandatory only when "Within Range" or "Equals" is selected.
    • Mandatory when "Within Range" is selected (An example is "255.255.255.192".)
    "type"String"DEPENDENCY"
    "ALGORITHM"
    "CO_OCCURRENCE"
    The alert correlation policy type.
    "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".
    "dependencyCorrelation"StringCorrelate alerts on upstream and downstream resources.
    • "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"
      • "device_group"
      • "service_group"
      • "site"
      • "alert_description"
    • 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.
    If a user wants to correlate alerts which exactly share same IP address 172.34.213, provide the "property": "ip_address" and "matchType": "Identical" fields. See Matching conditions table for detailed information on match types.
    • "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.
    • "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": "ESX Host in SJ-West is Down",
     "filterCriteria": {
       "filterBased": "true",
       "matchingType": "ALL",
       "rules": [{
           "filterType": "nativeAttributes",
           "entityName": "host_name",
           "operator": "Contains",
           "entityValue": "vm"
         },
         {
           "filterType": "customAttributes",
           "entityName": "Agent Status",
           "operator": "Equals",
           "entityValue": "Down"
         }
       ]
     },
     "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": "ESX Host in SJ-West is Down",
    	"enabled": true,
    	"precedence": 28,
    	"filterCriteria": {
    		"filterBased": true,
    		"matchingType": "ALL",
    		"rules": [{
    			"filterType": "nativeAttributes",
    			"entityName": "host_name",
    			"operator": "CONTAINS",
    			"entityValue": "vm"
    		}, {
    			"filterType": "customAttributes",
    			"entityName": "Agent Status",
    			"operator": "Equals",
    			"entityValue": "Down"
    		}]
    	},
    	"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"
    	},
    	"createdTime": "2018-04-27T13:14:07+0000",
    	"updatedTime": ""
    }

    Create alert correlation policy with algorithm-based correlation

    Sample request

    {
    	"name": "Correlate alerts on parked VMwares",
    	"filterCriteria": {
    		"filterBased": "true",
    		"matchingType": "ALL",
    		"rules": [{
    				"filterType": "nativeAttributes",
    				"entityName": "host_name",
    				"operator": "Contains",
    				"entityValue": "vm"
    			},
    			{
    				"filterType": "customAttributes",
    				"entityName": "Agent Status",
    				"operator": "Equals",
    				"entityValue": "Down"
    			}
    		]
    	},
    	"type": "ALGORITHM",
    	"algorithmCorrelation": {
    		"alertsTimeWindow": "20",
    		"matchingConditions": [{
    				"property": "subject",
    				"matchType": "Identical"
    			},
    			{
    				"property": "alert_metric",
    				"matchType": "Nearly Identical"
    			}
    		],
    		"primaryAlertSubject": "Agent down on parked VMwares"
    	}
    }

    Sample response

    {
    	"id": "POLICY-AC-7556bcf6-4cc2-44ba-ba1f-3ca5a211bcb3",
    	"name": "Correlate alerts on parked VMwares",
    	"enabled": true,
    	"precedence": 29,
    	"filterCriteria": {
    		"filterBased": true,
    		"matchingType": "ALL",
    		"rules": [{
    			"filterType": "nativeAttributes",
    			"entityName": "host_name",
    			"operator": "Contains",
    			"entityValue": "vm"
    		}, {
    			"filterType": "customAttributes",
    			"entityName": "Agent Status",
    			"operator": "Equals",
    			"entityValue": "Down"
    		}]
    	},
    	"type": "ALGORITHM",
    	"algorithmCorrelation": {
    		"alertsTimeWindow": 20,
    		"matchingConditions": [{
    			"property": "subject",
    			"matchType": "Identical"
    		}, {
    			"property": "alert_metric",
    			"matchType": "Nearly Identical"
    		}],
    		"primaryAlertSubject": "Agent down on parked VMwares"
    	},
    	"createdBy": {
    		"loginName": "John_Smith",
    		"lastName": "Smith",
    		"firstName": "John",
    		"email": "john.smith@myorganization.com"
    	},
    	"createdTime": "2018-04-27T13:14:07+0000",
    	"updatedTime": ""
    }

    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": "agent_status",
    				"operator": "Equals",
    				"entityValue": "up"
    			}
    		]
    	},
    	"type": "CO_OCCURRENCE"
    }

    Sample response

    {
    	"id": "POLICY-AC-1556bcf6-7cc2-44ba-ba1f-8ca5a211bcb3",
    	"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": "agent-status",
    			"operator": "Equals",
    			"entityValue": "up"
    		}]
    	},
    	"type": "CO_OCCURRENCE",
    	"createdBy": {
    		"loginName": "opsramp_api_user",
    		"lastName": " ",
    		"firstName": "OpsRamp API User",
    		"email": "john.smith@myorganization.com"
    	},
    	"createdTime": "2018-08-27T13:14:07+0000",
    	"updatedTime": ""
    }

    Create alert correlation policy with IP address filter

    Sample request

    {
    	"name": "Server-SJ Alerts",
            "type": "ALGORITHM",
    	"filterCriteria": {
    		"filterBased": "true",
    		"matchingType": "ALL",
    		"rules": [{
    				"filterType": "nativeAttributes",
    				"entityName": "ip_address",
                                    "ipMatchingConditions":
                                      {
    				    "ipAddressMatchType":"Within Range",
    				    "ipAddress":"192.168.5.130",
    				   "netmask":"255.255.255.192"
    				}
                              }]
    	                },
    
     "algorithmCorrelation": {
    	"alertsTimeWindow":"20",
    	"matchingConditions":[
    	      {
    		"property":"host_name",
    		"matchType":"Identical"
    	      }
    
                 ],
    	"primaryAlertSubject":"IP policy api demo"
    }

    Sample response

    {
        "id": "POLICY-AC-e275116e-c457-47be-bd25-9eef3c1d7976",
        "name": "IP policy api demo",
        "enabled": true,
        "precedence": 88,
        "filterCriteria": {
            "filterBased": true,
            "matchingType": "ALL",
            "rules": [
                {
                    "filterType": "nativeAttributes",
                    "entityName": "ip_address",
                    "ipMatchingConditions": {
                        "ipAddressMatchType": "Within Range",
                        "ipAddress": "192.168.5.130",
                        "netmask": "255.255.255.192"
                    }
                }
            ]
        },
        "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:42:42+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" : ""
    }