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 Control-M Automation API is set up, as described in Setting Up the API.
Ensure that Git is installed, which can be obtained from Git Downloads.
Run the following command to verify that you have local copies of the tutorial samples from GitHub and the source code:

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

Begin

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.
1. 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"
}
```
2. Run the following command:
  
  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 Control-M SaaS, by selecting the Send Alerts to External Event Management System and Alert Type system settings in the Configuration domain. For more information, see Configuring System Settings.
Use one of the following options to open the stream of alerts from Control-M SaaS.
- Run the run alerts:stream::open command through the CLI:
  
  ctm run alerts:stream::open
- Run the equivalent REST API command:
  
  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 at the end of this tutorial.
Prepare a JSON template file named alert_template.json to handle alerts from job processing, as in the following example.
Copy
```
{
    "fields":
    [
        {"id":"alertId"},
        {"application":"businessUnit"},
        {"message":"message"},
        {"time":"date_and_time"},
        {"jobName":"jobName"}
    ]
}
```
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.
Set the details that are provided with every alert using one of the following commands:
- Run the following run alerts:stream:template::set command through the CLI:
  
  ctm run alerts:stream:template::set -f alert_template.json
- Run the equivalent REST API command:
  
  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"
}
```
Set the Control-M SaaS 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:
Copy
```
{
    "message": "Alerts listener environment set to: myEnvironment"
}
```
Set your script for receiving alert data and handling alerts by running the following run alerts:listener:script::set command.
Copy
```
ctm run alerts:listener:script::set myScript
```
This command uses a sample script that is available in GitHub.

The following response indicates that the script was set successfully for alert handling:
Copy
```
{
    "message": "Alerts listener script path set to myScript"
}
```
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:
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:

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 the steps in this tutorial, beginning with opening the stream of alerts (typically on a different machine).