Exception Alerts Configuration

The following API commands enable you to configure Exception Alerts (xAlerts), which notify you of system failures in the database, communication network problems, and application errors and failures.

This feature requires Control-M/EM version 9.0.27 or higher.

config exceptionAlerts::get

The config exceptionAlerts::get command enables you to get a list of all exception alerts, with details about each alert.

  • CLI

  • REST

ctm config exceptionAlerts::get [updateLevel]

The following example shows the REST API syntax for the config exceptionAlerts::get command in cURL.

Copy 
updateLevel=4
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H -X GET "$AuthHeader" "$endpoint/config/exceptionAlerts/$updateLevel"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

The optional updateLevel number enables you to filter the list of returned exception alerts to those that were issued since a previous run of the config exceptionAlerts::get command, as specified by the updateLevelIndex in the previous response. For no filtering, do not specify a number or use a value of 0.

Response

The following sample response presents the details of one exception alert:

Copy 
{
  "updateLevelIndex": 4,
  "exceptionAlerts": [
    {
      "alertID": 1,
      "severity": "W",
      "status": "Not handled",
      "componentType": "CTM Server",
      "componentName": "st-ntw-ijklz",
      "dateTime": "07/05/2026 12:30 PM",
      "messageCode": "CTM_1",
      "message": "Database archive is off. No database backups are running. You should  backup the database. Please refer to the DBUHotBackup utility in the Utilities Guide. For suppressing backup messages refer to article 000154266",
      "comment": "",
      "repeatCounter": 2
    }
  ]
}

The following table describes the config exceptionAlerts::get response details that are shown in the above response:

Parameter

Description

updateLevelIndex

Presents the numeric index of this run of the config exceptionAlerts::get command.

You can use this index in future runs to limit the returned list to only those alerts that were issued since this run.

alertID

Presents the numeric value used as a key (index) to identify the exception alert.

severity

Presents one of the following levels of severity (listed in ascending severity) for the exception alert:

  • W: Warning

  • E: Error

  • S: Severe

status

Presents the exception alert status, either Handled or Not Handled.

You can use the config exceptionAlert:handled::set or config exceptionAlert:unhandled::set command to change the status.

componentType

Presents the Control-M component type associated with the exception alert. The following are examples of component types:

  • CMS

  • Agent

  • Load Balancer

  • Control-M/Server

  • Control-M/EM

componentName

Presents the name of the Control-M component associated with the exception alert.

dateTime

Presents the date and time when the exception alert occured.

Format: MM/DD/YYYY HH:MM AM/PM

messageCode

Presents the message code of the reported exception alert.

message

Presents the full text of the exception alert message with full information about the exception.

comment

Presents the current user note associated with the exception alert.

You can use the config exceptionAlert:note::update command to change the note.

repeatCounter

Presents the number of times that this exception alert was reported.

config exceptionAlert:handled::set

The config exceptionAlert:handled::set command enables you to set the status of an exception alert to Handled.

  • CLI

  • REST

ctm config exceptionAlert:handled::set <alertId>

The following example shows the REST API syntax for the config exceptionAlert:handled::set command in cURL.

Copy 
alertId=12
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H -X POST "$AuthHeader" \
"$endpoint/config/exceptionAlert/$alertId/handled"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

The alertId is the numeric value used as a key (index) to identify the alert. You can obtain this ID from the response to the config exceptionAlerts::get command.

If annotation is enabled for the Configuration Management category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config exceptionAlert:unhandled::set

The config exceptionAlert:unhandled::set command enables you to set the status of an exception alert to Not Handled.

  • CLI

  • REST

ctm config exceptionAlert:unhandled::set <alertId>

The following example shows the REST API syntax for the config exceptionAlert:unhandled::set command in cURL.

Copy 
alertId=12
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H -X POST "$AuthHeader" \
"$endpoint/config/exceptionAlert/$alertId/unhandled"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

The alertId is the numeric value used as a key (index) to identify the alert. You can obtain this ID from the response to the config exceptionAlerts::get command.

If annotation is enabled for the Configuration Management category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config exceptionAlert:note::update

The config exceptionAlert:note::update command enables you to update the note text that is displayed as a comment in the Control-M/EM Alerts window.

  • CLI

  • REST

ctm config exceptionAlert:note::update <alertId> "<userNote>"

The following example shows the REST API syntax for the config exceptionAlert:note::update command in cURL.

Copy 
alertId=12
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H -X POST "$AuthHeader"  \
"$endpoint/config/exceptionAlert/$alertId/note/" -d '{"userNote":"Investigated and resolved."}'

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

The following table describes the config exceptionAlert:note::update command parameters.

Parameter

Description

alertId

Defines a numeric value that is used as a key (index) to identify the alert.

You can obtain this ID from the response to the config exceptionAlerts::get command.

userNote

Defines the note text.

If annotation is enabled for the Configuration Management category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

config exceptionAlerts:remove::delete

The config exceptionAlerts:remove::delete command enables you to delete all exception alerts that are older than a specified number of days.

  • CLI

  • REST

ctm config exceptionAlerts:remove::delete <daysToKeep>

<daysToKeep> is the number of days to keep alerts. Alerts that are older than this number of days are deleted.

The following example shows the REST API syntax for the config exceptionAlerts:remove::delete command in cURL. The optional ? switch enables you to limit deletion to alerts that are older than the number of days that you want to keep.

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H -X DELETE "$AuthHeader" \
"$endpoint/config/exceptionAlerts/remove?daysToKeep=50"

To determine the correct AuthHeader value—"Authorization: Bearer $token" or "x-api-key: $token"—see Authentication Tokens.

If annotation is enabled for the Database Maintenance category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.