In this page:

1 GET Retrieve all Alerts
2 GET Get an Alert
3 POST Execute (Async) an Alert
4 GET Get an Alert Execution
5 GET Download an Alert Execution Result
6 POST Duplicate an Alert
7 POST Add an Alert
8 PUT Edit an Alert
9 DELETE Delete an Alert

GET Retrieve all Alerts

Description:

This API retrieves all alerts.

Required Roles:

One of the following:

A custom role that allows access to “View Alerts”.
The OpDashAdminRole builtin role.
The OpDashPowerUserRole builtin role.

URI:

/op/api/v2/alerts/{{productView}}

Request:

The request should use the GET method with the following URL parameters:

Name	Required/Optional	Description	Type	Available Options

Name	Required/Optional	Description	Type	Available Options
productView	Required	The product view.	String	APIC IDG

Successful Response:

The response includes the following fields in its resultelement:

Name	Description	Type	Available Options

Name	Description	Type	Available Options
alerts		Array of Element
alerts[].id	The ID of the alert.	Long
alerts[].isSystemHealthMetric	Whether or not the alert is a metric.	Boolean
alerts[].isActive	Whether or not the alert will be scheduled for execution.	Boolean
alerts[].name	The alert name.	String
alerts[].description	Text description of the alert’s definition.	String
alerts[].productView	The product view assigned to the alert.	String	IDG APIC
alerts[].indexSets	Which OpenSearch index sets will be queried (according to product view).	String (Comma separated)	See Index Sets.
alerts[].documentType	Which OpenSearch document types will be queried (according to product view)	String	See Document type.
alerts[].jsonQuery	An OpenSearch query.	String (JSON)
alerts[].jsonParameters	Key-Value Pairs to Replace Values within the Query (JSON).	String (JSON)
alerts[].schedule	The scheduling definition using a simplified version of the Cron scheduling format.	String	format: sec min hour day month weekday year
alerts[].recipients	A list of email addresses the alert will be emailed to.	Array of Strings
alerts[].filtersParameters	Alert filters (according to product type and document type). Provided as Key-Value Pairs, where: The key is the filter name and the value is the filter value. The key is the filter operator ( filter name + `Op` ) and the value is the operator ( eq / ne / gt / gte / lte / lt).	Element	See Alert Filters.
alerts[].serviceNameFieldOverride	Apply the service filter value to a specific Store field. You may leave this field empty unless otherwise advised.	String
alerts[].lastUpdateTimeInMillis	Time the alert was created.	Long
alerts[].lastUpdateUserName	The user who created the alert.	String
alerts[].isPublishToMail	Whether or not an email will be sent.	Boolean
alerts[].isPublishToSyslog	Whether or not a syslog message will be sent.	Boolean
alerts[].isPublishToMailWs	Whether or not an email will be sent via webservice.	Boolean
alerts[].errorThreshold	If the alert value exceeds the error threshold value, the alert is assigned with a severity of error.	Double	Thresholds can be set only for health metrics that support thresholds (such as Frequency or Flat-Line)
alerts[].warningThreshold	If the alert value exceeds the warning threshold value, the alert is assigned with a severity of warning.	Double	Thresholds can be set only for health metrics that support thresholds (such as Frequency or Flat-Line)
alerts[].warningDamagePoints	The amount of damage points that are assigned for this alert if the alert has a severity of warning. When a specific device has only alerts in a warning severity, and the accumulated damage points of these alerts exceed its Damage Points Threshold, the device transitions into an error state in the System Health dashboard.	Double	Thresholds can be set only for health metrics that support thresholds (such as Frequency or Flat-Line)
alerts[].alertType	Type of the alert query.	String	Frequency Flatline Any List
alerts[].comparator	The comparator used to compare between the OpenSearch query result and the error threshold.	String	Equals NotEquels GreaterThan GreaterThanOrEquals LessThan LessThanOrEquals In NotIn Each alert type supports different comparators, for further details see Operators
alerts[].apiReference	Unique alert UUID.	String
alerts[].valueFieldName	The field name which field value is compared to the list of values.	String	Only applicable for alert type "List" and “Frequency“
alerts[].listOfValues	For alert type “Frequency“, is is a delimited final result list which will force the result to include only specific values. Missing values will be added with 0 fetched documents (thus allowing the user to identify missing values such as unused services). For alert type “List”, it is a delimited blacklist or a whitelist of values.	String	Only applicable for alert type "List" and “Frequency“
alerts[].listDelimiter	The delimiter used to delimit the list of values.	String	Only applicable for alert type "List" and “Frequency“
alerts[].investigateUri	The investigate link displays the data that triggered each alert in DPOD Web Console.	String
alerts[].aggregationNamesToIgnore	Aggregation names to ignore in results.	String (Comma separated)

Example:

{
    "resultCode": "SUCCESS",
    "resultMessage": "Alerts retrieved successfully",
    "result": {
        "alerts": [
            {
                "id": 26,
                "isSystemHealthMetric": false,
                "isActive": false,
                "name": "API Error Message Count Alert",
                "description": "Alert when more than 10 API trans. ended with a specific error message",
                "productView": "APIC",
                "indexSets": "apic-log",
                "documentType": "APIC_LOGICAL_TRANS",
                "jsonQuery": "{\"query\":{\"bool\":{\"must\":{\"match_all\":{}},\"filter\":{\"bool\":{\"must\":[{\"term\":{\"documentType\":{\"value\":27}}},{\"match_phrase\":{\"errorMessage\":\"$messageTextSubstring\"}},{\"terms\":{\"recordType\":[\"R4\"]}},{\"bool\":{\"should\":[{\"term\":{\"recordCounter\":{\"value\":\"1\"}}},{\"bool\":{\"must_not\":[{\"exists\":{\"field\":\"recordCounter\"}}]}}],\"minimum_should_match\":\"1\"}}]}}}},\"aggs\":{\"API\":{\"terms\":{\"field\":\"apiName\",\"size\":1000,\"shard_size\":10000,\"order\":{\"_count\":\"desc\"}}}},\"size\":0}",
                "jsonParameters": "{\"messageTextSubstring\":\"Failed to establish a backside connection\"}",
                "schedule": "",
                "recipients": [],
                "filtersParameters": {
                    "timeRangeType": "recent",
                    "timeRangePeriod": "600000"
                },
                "lastUpdateTimeInMillis": 1719389034455,
                "lastUpdateUserName": "Installer",
                "isPublishToMail": false,
                "isPublishToSyslog": false,
                "isPublishToMailWs": false,
                "errorThreshold": 10.0,
                "alertType": "Frequency",
                "comparator": "GreaterThan",
                "apiReference": "EDBD6F2B-A576-4619-AC63-2594A10F7EC6",
                "investigateUri": "apicTransactions:-apicApiNameOp:eq-apicApiName:${result:API}-errorMessageOp:eq-errorMessage:${parameter:messageTextSubstring}"
            },
            { .....}

GET Get an Alert

Description:

This API retrieves a specific alert.

Required Roles:

One of the following:

A custom role that allows access to “View Alerts”.
The OpDashAdminRole builtin role.
The OpDashPowerUserRole builtin role.

URI:

/op/api/v2/alert/{{productView}}/{{alertApiReferenceId}}

Request:

The request should use the GET method with the following URL parameters:

Name	Required/Optional	Description	Type	Available Options

Name	Required/Optional	Description	Type	Available Options
productView	Required	The product view.	String	APIC IDG
alertApiReferenceId	Required	The alert UUID.	String

Successful Response:

The response includes the following fields in its resultelement:

Name	Description	Type	Available Options

Name	Description	Type	Available Options
id	The ID of the alert.	Long
isSystemHealthMetric	Whether or not the alert is a metric.	Boolean
isActive	Whether or not the alert will be scheduled for execution.	Boolean
name	The alert name.	String
description	Text description of the alert’s definition.	String
productView	The product view assigned to the alert.	String	IDG APIC
indexSets	Which OpenSearch index sets will be queried (according to product view).	String (Comma separated)	See Index Sets.
documentType	Which OpenSearch document types will be queried (according to product view)	String	See Document type.
jsonQuery	An OpenSearch query.	String (JSON)
jsonParameters	Key-Value Pairs to Replace Values within the Query (JSON).	String (JSON)
schedule	The scheduling definition using a simplified version of the Cron scheduling format.	String	format: sec min hour day month weekday year
recipients	A list of email addresses the alert will be emailed to.	Array of Strings
filtersParameters	Alert filters (according to product type and document type). Provided as Key-Value Pairs, where: The key is the filter name and the value is the filter value. The key is the filter operator ( filter name + `Op` ) and the value is the operator ( eq / ne / gt / gte / lte / lt).	Element	See Alert Filters.
serviceNameFieldOverride	Apply the service filter value to a specific Store field. You may leave this field empty unless otherwise advised.	String
lastUpdateTimeInMillis	Time the alert was created.	Long
lastUpdateUserName	The user who created the alert.	String
isPublishToMail	Whether or not an email will be sent.	Boolean
isPublishToSyslog	Whether or not a syslog message will be sent.	Boolean
isPublishToMailWs	Whether or not an email will be sent via webservice.	Boolean
errorThreshold	If the alert value exceeds the error threshold value, the alert is assigned with a severity of error.	Double	Thresholds can be set only for health metrics that support thresholds (such as Frequency or Flat-Line)
warningThreshold	If the alert value exceeds the warning threshold value, the alert is assigned with a severity of warning.	Double	Thresholds can be set only for health metrics that support thresholds (such as Frequency or Flat-Line)
warningDamagePoints	The amount of damage points that are assigned for this alert if the alert has a severity of warning. When a specific device has only alerts in a warning severity, and the accumulated damage points of these alerts exceed its Damage Points Threshold, the device transitions into an error state in the System Health dashboard.	Double	Thresholds can be set only for health metrics that support thresholds (such as Frequency or Flat-Line)
alertType	Type of the alert query.	String	Frequency Flatline Any List
comparator	The comparator used to compare between the OpenSearch query result and the error threshold.	String	Equals NotEquels GreaterThan GreaterThanOrEquals LessThan LessThanOrEquals In NotIn Each alert type supports different comparators, for further details see Operators
apiReference	Unique alert UUID.	String
valueFieldName	The field name which field value is compared to the list of values.	String	Only applicable for alert type "List" and “Frequency“
listOfValues	For alert type “Frequency“, is is a delimited final result list which will force the result to include only specific values. Missing values will be added with 0 fetched documents (thus allowing the user to identify missing values such as unused services). For alert type “List”, it is a delimited blacklist or a whitelist of values.	String	Only applicable for alert type "List" and “Frequency“
listDelimiter	The delimiter used to delimit the list of values.	String	Only applicable for alert type "List" and “Frequency“
investigateUri	The investigate link displays the data that triggered each alert in DPOD Web Console.	String
aggregationNamesToIgnore	Aggregation names to ignore in results.	String (Comma separated)

Example:

{
    "resultCode": "SUCCESS",
    "resultMessage": "Alert retrieved successfully",
    "result": {
        "id": 41,
        "isSystemHealthMetric": false,
        "isActive": false,
        "name": "API Error Message Count Alert Copy",
        "description": "Alert when more than 10 API trans. ended with a specific error message",
        "productView": "APIC",
        "indexSets": "apic-log",
        "documentType": "APIC_LOGICAL_TRANS",
        "jsonQuery": "{\"query\":{\"bool\":{\"must\":{\"match_all\":{}},\"filter\":{\"bool\":{\"must\":[{\"term\":{\"documentType\":{\"value\":27}}},{\"match_phrase\":{\"errorMessage\":\"$messageTextSubstring\"}},{\"terms\":{\"recordType\":[\"R4\"]}},{\"bool\":{\"should\":[{\"term\":{\"recordCounter\":{\"value\":\"1\"}}},{\"bool\":{\"must_not\":[{\"exists\":{\"field\":\"recordCounter\"}}]}}],\"minimum_should_match\":\"1\"}}]}}}},\"aggs\":{\"API\":{\"terms\":{\"field\":\"apiName\",\"size\":1000,\"shard_size\":10000,\"order\":{\"_count\":\"desc\"}}}},\"size\":0}",
        "jsonParameters": "{\"messageTextSubstring\":\"Failed to establish a backside connection\"}",
        "schedule": "",
        "recipients": [],
        "filtersParameters": {
            "timeRangeType": "recent",
            "timeRangePeriod": "600000"
        },
        "lastUpdateTimeInMillis": 1727695016120,
        "lastUpdateUserName": "admin",
        "isPublishToMail": false,
        "isPublishToSyslog": false,
        "isPublishToMailWs": false,
        "errorThreshold": 10.0,
        "alertType": "Frequency",
        "comparator": "GreaterThan",
        "apiReference": "938F0930-5E5F-4775-BFA3-312662C37FB1",
        "investigateUri": "apicTransactions:-apicApiNameOp:eq-apicApiName:${result:API}-errorMessageOp:eq-errorMessage:${parameter:messageTextSubstring}"
    }
}

POST Execute (Async) an Alert

Description:

This API executes a specific alert.

Required Roles:

One of the following:

A custom role that allows access to “View Alerts”.
The OpDashAdminRole builtin role.
The OpDashPowerUserRole builtin role.

URI:

/op/api/v2/alert/{{productView}}/{{alertApiReferenceId}}/executeAsync

Request:

The request should use the POST method with the following URL parameters:

Name	Required/Optional	Description	Type	Available Options

Name	Required/Optional	Description	Type	Available Options
productView	Required	The product view.	String	APIC IDG
alertApiReferenceId	Required	The alert UUID.	String

The request should use the POST method with the following fields in its body:

Name	Required/Optional	Description	Type	Available Options

Name

Required/Optional

Description

Type

Available Options

recipients

Required

A list of email addresses the alert will be emailed to.

Array of Strings

filtersParameters

Required

Alert filters (according to product type and document type).
Provided as Key-Value Pairs, where:

The key is the filter name and the value is the filter value.
The key is the filter operator ( filter name + Op ) and the value is the operator ( eq / ne / gt / gte / lte / lt).

Element

See Alert Filters.

Example:

{
    "recipients": [
        "test@com"
    ],
    "filtersParameters": {
        "timeRangeType": "recent",
        "timeRangePeriod": "86400000",
        "deviceName": "idg_10_5_0_a"
    }
}

Successful Response:

The response includes the following fields in its resultelement:

Name	Description	Type	Available Options

Name	Description	Type	Available Options
executionId	The alert execution ID.	Long

Example:

GET Get an Alert Execution

Description:

This API retrieves execution details for a specific alert execution.

Required Roles:

One of the following:

A custom role that allows access to “View Alerts”.
The OpDashAdminRole builtin role.
The OpDashPowerUserRole builtin role.

URI:

/op/api/v2/alertexecution/{{productView}}/{{executionId}}

Request:

The request should use the GET method with the following URL parameters:

Name	Required/Optional	Description	Type	Available Options

Name	Required/Optional	Description	Type	Available Options
productView	Required	The product view.	String	APIC IDG
executionId	Required	The alert execution ID.	String

Successful Response:

The response includes the following fields in its resultelement:

Name	Description	Type	Available Options

Name	Description	Type	Available Options
executionId	The alert execution ID.	Long
filters	Alert filters (according to product type and document type). Provided as Key-Value Pairs, where: The key is the filter name and the value is the filter value. The key is the filter operator ( filter name + `Op` ) and the value is the operator ( eq / ne / gt / gte / lte / lt).	String	See Alert Filters.
executingUserName	The user who executed this alert execution.	String
status	Alert execution status.	String	Requested Pending Executing OK Error
requestTimeInMillis	Request time in milliseconds.	Long
pendingTimeInMillis	Pending time in milliseconds.	Long
executionTimeInMillis	Execution time in milliseconds.	Long
completionTimeInMillis	Completion time in milliseconds.	Long
message	The message that indicates whether there are any alerts.	String	"Execution finished with no alerts." "Execution finished with X alerts."

Example:

GET Download an Alert Execution Result

Description:

This API downloads an alert execution result by its execution ID.

Required Roles:

One of the following:

A custom role that allows access to “View Alerts”.
The OpDashAdminRole builtin role.
The OpDashPowerUserRole builtin role.

URI:

/op/api/v2/alertexecution/{{productView}}/{{executionId}}/download

Request:

The request should use the GET method with the following URL parameters:

Name	Required/Optional	Description	Type	Available Options

Name	Required/Optional	Description	Type	Available Options
productView	Required	The product view.	String	APIC IDG
executionId	Required	The alert execution ID.	String

Successful Response:

The response content type is application/octet-stream and includes the alert execution result file content as its body.
To open the alert execution result file, save the response content as a file with an extension of .json and open the file.
The Content-Disposition response header value includes a suggested file name (e.g.: attachment; filename=alert-<alert name + "-" + execution ID>.json).

IBM DPOD v1.0.22.x

IBM DataPower Operations Dashboard v1.0.22.x

Alerts REST API

GET Retrieve all Alerts

Description:

Required Roles:

URI:

Request:

Successful Response:

GET Get an Alert

Description:

Required Roles:

URI:

Request:

Successful Response:

POST Execute (Async) an Alert

Description:

Required Roles:

URI:

Request:

Successful Response:

GET Get an Alert Execution

Description:

Required Roles:

URI:

Request:

Successful Response:

GET Download an Alert Execution Result

Description:

Required Roles:

URI:

Request:

Successful Response:

POST Duplicate an Alert

POST Add an Alert

PUT Edit an Alert

DELETE Delete an Alert