Sending Events to External Monitoring Tools

This tutorial demonstrates how to set up the transfer of alerts to an external client for monitoring through external tools, such as an event management system.

Before you begin

Ensure that you meet the following prerequisites:

  • You have successfully completed API setup, as described in Setting Up the API. You have a valid API endpoint and API token, and you have set up at least one environment.

  • You have Git installed. If not, obtain it from the Git Downloads page.

  • You have local copies of the tutorial samples from GitHub and a local copy of the source code using the git clone command:

    Copy
    git clone https://github.com/controlm/automation-api-quickstart.git

Step 1 - Enable External Alerts

Enable sending alerts to external event management systems and set the type of alerts by running the System Settings Configuration command to set the enableExternalAlerts property and the externalAlertTypes property.

First ensure that the JSON file that contains your system settings (in this example, systemsettings.json) contains the following properties:

Copy
"enableExternalAlerts": {
    "value": "true"
},
"externalAlertTypes": {
    "value": "Alerts"
}

Then run the following command:

Copy
ctm config systemsettings::set systemsettings.json

The following response indicates that external events were enabled successfully:

Copy
{
    "message": "System Setting were saved"
}

Alternatively, you can enable external alerts and select the type of alerts through Helix Control-M, by selecting the Send Alerts to External Event Management System and Alert Type system settings in the Configuration domain. For more information, see Defining System Settings.

Step 2 - Open an Alerts Stream

Use one of the following options to open the stream of alerts from Helix Control-M.

  • Run the equivalent REST API command:

    Copy
    curl -H "x-api-key: $token" -H "Content-Type: application/json"
        -X POST "$endpoint/run/alerts/stream/open"

A successful response returns a WebSocket URL for the connection, as in the following example:

Copy
{
    "url": "wss://xyz-66095-alerts.us1.ci.ctmsaas.com"
}
  • You can have only one open Alerts stream at a time.

  • This step is optional. If you do not open the stream at this point, it opens automatically when you start the Alerts listener in Step 6 - Start the Alerts Listener.

Step 3 - Set Alert Details

Prepare a JSON template file named alert_template.json. Through this file, you can override the default alert details with a subset of alert fields, and you can modify the names of fields and set the order of their appearance, as described in External Alerts Fields and Templates. Here is an example of the contents of this file for alerts from job processing:

Copy
{
    "fields":
    [
        {"id":"alertId"},
        {"application":"businessUnit"},
        {"message":"message"},
        {"time":"date_and_time"},
        {"jobName":"jobName"}
    ]
}

Now that your template is ready, use one of the following options to set the details that are provided with every alert.

  • Run the equivalent REST API command:

    Copy
    curl -H "x-api-key: $token" -H "Content-Type: application/json"
    -X POST -d "@alert_template.json" "$endpoint/run/alerts/stream/template"

The following response indicates that alert fields were set successfully:

Copy
{
    "message": "JSON template updated successfully"
}

Step 4 - Set the Environment for Alert Listening

Set the Helix Control-M environment to listen to for alerts by running the run alerts:listener:environment::set command:

Copy
ctm run alerts:listener:environment::set myEnvironment

The following response indicates that the environment was set successfully for alert listening:

Copy
{
    "message": "Alerts listener environment set to: myEnvironment"
}

Step 5 - Set a Script for Alert Handling

Set your script for receiving alert data and handling alerts by running the run alerts:listener:script::set command.

A sample script is available in GitHub for you to download and submit through this command.

Copy
ctm run alerts:listener:script::set myScript

The following response indicates that the script was set successfully for alert handling:

Copy
{
    "message": "Alerts listener script path set to myScript"
}

Step 6 - Start the Alerts Listener

Start the Alerts listener for the defined environment by running the run alerts:listener::start command.

Copy
ctm run alerts:listener::start

A successful response returns a process ID for the Alerts listener, as in the following example:

Copy
{
    "listenerPid": "1920"
}

You can have only one listener running at a time. If you want to open another listener (for example, from a different machine, using a different API token), you must first stop the running listener, using the same API token that was used to start that listener. Use the following command to stop the listener:

Copy
ctm run alerts:listener::stop

A successful response specifies the process ID of the stopped run of the Alerts listener.

You can now start the listener by repeating Steps 2 to 6 in this tutorial (typically on a different machine).