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 by running the System Settings Configuration command to set the enableExternalAlerts property.

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

"enableExternalAlerts": {
    "value": "true"
}

Then run the following command:

ctm config systemsettings::set systemsettings.json

The following response indicates that external events were enabled successfully:

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

Step 2 - Open an Alerts Stream

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

• Run the run alerts:stream::open command through the CLI:

  Copy

  ctm run alerts:stream::open

• 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:

{
    "url": "wss://xyz-66095-alerts.us1.ci.ctmsaas.com"
}

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:

{
    "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 run alerts:stream:template::set command through the CLI:

  Copy

  ctm run alerts:stream:template::set -f alert_template.json

• 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:

{
    "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:

ctm run alerts:listener:environment::set myEnvironment

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

{
    "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.

ctm run alerts:listener:script::set myScript

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

{
    "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.

ctm run alerts:listener::start

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

{
    "listenerPid": "1920"
}

ctm run alerts:listener::stop