Merge pull request #126 from davidctm/master

doc update

Author: nathanw9722

helix-control-m/2-external-monitoring-tools-examples/README.md

@@ -1,6 +1,6 @@
 # BMC Helix Control-M API - External Monitoring Tools Examples
 
-This folder contains sample scripts that can be used to transfer alerts to external tools, such as an event management system or a monitoring solution.
+This folder contains sample scripts that can be used to send BMC Helix Control-M alerts to external applications, such as event management systems, monitoring tools or ITSM solutions.
 
 ## Description
 

helix-control-m/2-external-monitoring-tools-examples/alerts-data-as-variables/README.md

@@ -1,12 +1,12 @@
 ## Description
 
-This Linux (bash) script parses the alert data into individual variables.
+This shell script ([**alerts_variables.sh**](alerts_variables.sh)) parses the alert data into individual variables.
 
-This simplifies using any alert fields in the script, which then can be used as `$<field>` (e.g. $runId, $message, $jobName, etc) when calling the command used to send the alerts to an external tool.
+It simplifies using any alert fields in the script, which can be then used as `$<field>` (e.g. $runId, $message, $jobName, etc) when calling the command used to send alerts to an external tool.
 
 As an example, the alert data is saved into a file, but this could be replaced by any other action.
 
-## Usage
+## Instructions
 
 - If you use the script as it is (saving the alert data into a file), update the **alerts_dir** and **alerts_file** variables with your custom file location.
 
@@ -20,4 +20,10 @@ The alert data is passed as parameters to the script with the format `<field1>:
 
 As some fields can have an empty value, it is not possible to simply reference the input parameters as $1, $2, $3, etc - as the order may change. This scripts simplifies using each field value in the script, which can be referenced simply as variables with the same field name, as in the the following example:
 
-    echo "$time | $id | $severity | $runId | $application | $jobName | $host | $message" >> myfile.txt
+    echo "$time | $id | $severity | $runId | $application | $jobName | $host | $message" >> myfile.txt
+
+## Versions
+
+| Date | Updated by | Changes |
+| - | - | - |
+| 2023-02-03 | David Fernández | First release |

helix-control-m/2-external-monitoring-tools-examples/alerts-data-to-json/README.md

@@ -1,10 +1,10 @@
 ## Description
 
-This Linux (bash) script converts the received alert data to JSON, which can be useful when an external tool is expecting the input data in such format.
+This shell script ([**alerts_json.sh**](alerts_json.sh)) converts the alert data to JSON, which can be useful when an external tool is expecting the input in such format.
 
-As an example, the alert data is saved into a file, but this could be replaced by any other action (e.g. sending the alert data in JSON via a webhook).
+As an example, the alert data is saved into a file, but this could be replaced by any other action (e.g. sending the alert data as a JSON payload via a webhook).
 
-## Usage
+## Instructions
 
 - If you use the script as it is (saving the JSON data into a file), update the **alerts_dir** and **alerts_file** variables with your custom file location.
 
@@ -15,7 +15,7 @@ As an example, the alert data is saved into a file, but this could be replaced b
 The alert data is passed as parameters to the script with the format `<field1>: <value1> <field2>: <value2> [...]`, as in the following example:
 
     eventType: I id: 2193 server: IN01 fileName: runId: 00q2e severity: V status: 0 time: 20221126150057 user: updateTime: message: Ended not OK runAs: ctmagent subApplication: application: my-demos jobName: my-sample-job host: zzz-linux-agent-1 type: R closedByControlM: ticketNumber: runNo: 00001 notes:
-
+\
 The script parses the input data and converts it to JSON format, starting with the "*alertFields*" key and followed by an array containing all the alert fields and their corresponding values - as in the example below. This is the same JSON structure as the one received when connecting to the External Alerts service via a WebSocket client.
 
     {
@@ -42,4 +42,10 @@ The script parses the input data and converts it to JSON format, starting with t
           {"runNo" : "00001"},
           {"notes" : ""}
         ]
-    }
+    }
+
+## Versions
+
+| Date | Updated by | Changes |
+| - | - | - |
+| 2023-02-03 | David Fernández | First release |

helix-control-m/2-external-monitoring-tools-examples/alerts-to-bhom/README.md

@@ -0,0 +1,112 @@
+## Description
+
+This shell script ([**alerts_to_bhom.sh**](alerts_to_bhom.sh)) sends BMC Helix Control-M alerts as events to BMC Helix Operations Management.
+
+It parses the alert data coming from Helix Control-M (**HCTM**) into JSON format, and then sends it to Helix Operations Management (**BHOM**) using its event ingestion API. The JSON data is structured according to an event class which has to be previously created in BHOM.
+
+## Pre-requisites
+
+- **Configure the HCTM "External Alert Management" service** from the Automation API to execute the script every time an alert is raised.
+ 
+  - For more information, check the HCTM documentation for [Setting Up External Alerts](https://documents.bmc.com/supportu/controlm-saas/en-US/Documentation/Alerts.htm#SettingUpExternalAlerts) and the HCTM Automation API documentation for [External Alert Management](https://docs.bmc.com/docs/saas-api/run-service-941879047.html#Runservice-alert_managementExternalAlertManagement).
+
+  - As explained in the documentation, you need to use "run alerts:listener:script::set" to define the path to the script - and then open the alerts stream and start the alerts listener process.
+
+- **Create a new Event Class in BHOM**, using the definition from the [**bhom_ctm_event_class.json**](bhom_ctm_event_class.json) file.
+
+  This event class called "**ControlMAlert**" includes all the required fields from the HCTM alert data, plus one additional field to include a link to the job that generated the alert (when applicable). It also inherits all fields from its parent classes "IIMonitorEvent", "MonitorEvent" and the "Event" base class (check the BHOM documentation on [Event classification and formatting](https://docs.bmc.com/docs/helixoperationsmanagement/231/event-classification-and-formatting-1160751038.html) for more details).
+
+  - To create the event class, contact your BHOM administrator or follow the documentation for [Event management endpoints in the REST API](https://docs.bmc.com/docs/helixoperationsmanagement/231/event-management-endpoints-in-the-rest-api-1160751462.html) (*remember to select your product version*), and use the "POST /events/classes" endpoint.
+
+  - If the "IIMonitorEvent" event class is not available in your BHOM environment, you can update the json file to use the "MonitorEvent" class instead.
+   
+- **Import an Event Policy in BHOM**, using the [**bhom_ctm_event_policy.json**](bhom_ctm_event_policy.json) file.  **[OPTIONAL]**
+
+  This event policy can be useful when alerts are also managed from HCTM (e.g. when an operator uses the HCTM web interface to close an alert, modify the urgency or add a comment), and we want to automatically reflect those changes in BHOM. If the HCTM alerts are only going to be managed from BHOM, there is no need to import this event policy.
+
+  Depending on the case, remember to set the "**alert_updates**" variable in the script accordingly (Y/N). If set to "N", alert updates are not sent to BHOM (and the policy will never apply, even if imported). If set to "Y", it is recommended to use the policy to avoid creating duplicate events in BHOM every time the alert details are updated from HCTM.
+
+  The event policy will automatically 1) update existing events coming from HCTM if they already exist in BHOM (which happens when the alert "Status", "Urgency" or "Comment" are updated in HCTM), 2) map the status from the HCTM alert to the BHOM event (e.g. close the event in BHOM if the alert is closed in HCTM), and 3) record the last alert comment into the BHOM notes history. Be aware that, if the event is closed in BHOM and the associated alert is updated from HCTM, a new event (with the same "alertId") will be created.
+
+  - To import the event policy from the BHOM console, go to the "Configuration" menu and select "Event Policies", click on the import button (located on the top right corner, right to the "Create" button) and attach the json file. Once imported, remember to select the policy name and click on the "Enable" button.
+
+  - To import the event policy using the API, follow the BHOM documentation for [Event policy management endpoints in the REST API](https://docs.bmc.com/docs/helixoperationsmanagement/231/event-policy-management-endpoints-in-the-rest-api-1160751484.html), and use the "POST /event_policies" endpoint.
+
+## Instructions
+
+Before using the script, update the following variables:
+
+- **hctm_url** : enter the URL for the HCTM tenant (e.g. "*https://\<tenant name\>.us1.controlm.com*").
+- **hctm_name** : the default is "Helix Control-M", but can be updated to e.g. use different names for multiple HCTM environments (the value is assigned to the BHOM "location" field).
+- **bhom_url** : enter the URL for the BHOM event data endpoint (e.g. "*https://\<BMC Helix Portal URL\>/events-service/api/v1.0/events*"), as described in the BHOM documentation for [Policy, event data, and metric data management endpoints in the REST API](https://docs.bmc.com/docs/helixoperationsmanagement/231/policy-event-data-and-metric-data-management-endpoints-in-the-rest-api-1160751457.html).
+- **bhom_api_key** : enter a valid BHOM API key, which you can obtain from the BHOM console in the "Administration" menu, selecting "Repository" and clicking on "Copy API Key".
+- **sev_V/U/R** : update the three variables to set the HCTM to BHOM correspondence for the "severity" field according to your preferences (alerts coming from HCTM can be Very urgent, Urgent or Regular; while BHOM event severity can be CRITICAL, MAJOR, MINOR, WARNING, INFO, OK or UNKNOWN).
+- **alert_updates** : select whether you want to send or not updates of existing HCTM alerts to BHOM (which happens when the alert "Status", "Urgency" or "Comment" are updated in HCTM).
+
+Do NOT modify the following variables:
+
+- **bhom_class** : leave as is to use the previously imported "ControlMAlert" event class.
+- **alert_fields** : leave as is to use the default field names for HCTM alerts. If you have previously modified the JSON template for alerts in HCTM, restore the default alert fields (as documented in the [Alerts Template reference](https://docs.bmc.com/docs/saas-api/alerts-template-reference-1144242602.html)).
+- **bhom_slots** : leave as is to use the default event slots defined in the "ControlMAlert" class.
+
+## Additional information
+
+- The integration has been tested with:
+
+   - BMC Helix Control-M 9.0.21.080
+   - BMC Helix Operations Management 23.1
+
+- You can create an **Event Group** in BHOM to show HCTM alerts only:
+
+   - In the BHOM console, go to the "Configuration" menu, select "Groups" and click on "Create".
+   - In the "Group Information" section, enter the group name (e.g. "Helix Control-M") and a description.
+   - In the "Selection Query" section, go to "Event Selection Criteria" and add "Class Equals ControlMAlert".
+   - Save the Group. Now you can go to the "Monitoring" menu, select "Groups" and click on the one you just created to view only events related to HCTM.
+
+- You can create a custom **Table View** in BHOM to show any HCTM alert fields of your choice in the "Events" or "Groups" dashboards.
+
+   - Follow the steps in the BHOM documentation for [Creating table views](https://docs.bmc.com/docs/helixoperationsmanagement/231/creating-table-views-1160750840.html).
+   - For example, a custom table view can be used to show the "jobLink" field in the main event dashboard, which when clicked will open the HCTM web interface with a monitoring viewpoint showing the problematic job and its neighborhood (when the alert is related to a job, and as long as the user is already logged in the HCTM web interface).
+
+- If you get the error "*curl: (48) An unknown option was passed in to libcurl*" when testing the script, uncomment the following line: 
+
+  ``export LD_LIBRARY_PATH="/usr/lib64:$LD_LIBRARY_PATH"``
+
+- The following table shows the correspondence between the HCTM alert fields and the BHOM event slots (defined in the "ControlMAlert" class or inherited from its parent classes), plus additional information for fields which are modified in the script.
+
+  For more information on the HCTM alert fields, check the [Alerts Template reference](https://docs.bmc.com/docs/saas-api/alerts-template-reference-1144242602.html) documentation.
+
+  | HCTM alert field | BHOM event slot | Comments |
+  | - | - | - |
+  | ``eventType`` | ``eventType`` | |
+  | ``id`` | ``alertId`` | |
+  | ``server`` | ``ctmServer`` | |
+  | ``fileName`` | ``fileName`` | |
+  | ``runId`` | ``runId`` | |
+  | ``severity`` | ``severity`` | The value is updated to map the HCTM to BHOM correspondence. Not included in the "ControlMAlert" class, as it is inherited from the base class "Event". |
+  | ``status`` | ``alertStatus`` | |
+  | ``time`` | ``creation_time`` | The value is converted to the format expected by BHOM (Epoch time, in milliseconds). Not included in the "ControlMAlert" class, as it is inherited from the base class "Event". |
+  | ``user`` | ``ctmUser`` | |
+  | ``updateTime`` | ``updateTime`` | The value is converted to the format expected by BHOM (Epoch time, in milliseconds). |
+  | ``message`` | ``msg`` | Not included in the "ControlMAlert" class, as it is inherited from the base class "Event". |
+  | ``runAs`` | ``runAs`` | |
+  | ``subApplication`` | ``subApplication`` | |
+  | ``application`` | ``application`` | |
+  | ``jobName`` | ``jobName`` | |
+  | ``host`` | ``source_hostname`` | When the alert "host" value is empty, it defaults to the "source_identifier" event slot. Not included in the "ControlMAlert" class, as it is inherited from the base class "Event". |
+  | ``type`` | ``alertType`` | |
+  | ``closedByControlM`` | ``closedByControlM`` | |
+  | ``ticketNumber`` | ``ticketNumber`` | |
+  | ``runNo`` | ``runNo`` | |
+  | ``notes`` | ``alertNotes`` | |
+  | | ``jobLink`` | Additional slot included in the "ControlMAlert" class, which value is defined in the script using the HCTM tenant URL, runId, ctmServer and jobName.  |
+  | | ``location`` | The value is defined in the script using the "hctm_name" variable. Not included in the "ControlMAlert" class, as it is inherited from the base class "Event".  |
+  | | ``source_identifier`` | The value is defined in the script using the HCTM tenant URL (removing the "https://"). Not included in the "ControlMAlert" class, as it is inherited from the base class "Event". |
+
+- The script could be modified to also include the ``external_id`` slot from the "IIMonitorEvent" class, in order to associate the event with a CI (configuration item).*
+
+## Versions
+
+| Date | Updated by | Changes |
+| - | - | - |
+| 2023-03-18 | David Fernández | First release |

helix-control-m/2-external-monitoring-tools-examples/alerts-to-bhom/alerts_to_bhom.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+#
+# Sends BMC Helix Control-M (HCTM) alerts as events to BMC Helix Operations Management (BHOM)
+#
+# Notes : - The alert data is sent in JSON format to BHOM using its event ingestion API
+#         - The "ControlMAlert" event class must be previously imported in BHOM
+#         - Update variables below according to your environment and preferences
+#
+
+# Set HCTM parameters
+hctm_url=https://my-hctm-tenant.us1.controlm.com
+hctm_name="Helix Control-M"
+
+# Set BHOM parameters
+bhom_url=https://my-bmc-helix-portal.com/events-service/api/v1.0/events
+bhom_api_key=mybh0m12-1234-1234-1234-ap1k3y123456
+bhom_class="ControlMAlert"
+
+# Set HCTM to BHOM correspondence for the "severity" field
+# HCTM : V (Very urgent), U (Urgent), R (Regular) | BHOM : CRITICAL, MAJOR, MINOR, WARNING, INFO, OK, UNKNOWN
+sev_V="CRITICAL"
+sev_U="MAJOR"
+sev_R="MINOR"
+
+# Send updates of existing alerts? (Y/N)
+alert_updates="Y"
+
+# Declare arrays with the HCTM alert fields and BHOM slot names - DO NOT MODIFY
+alert_fields=("eventType" "id" "server" "fileName" "runId" "severity" "status" "time" "user" "updateTime" "message" "runAs" "subApplication" "application" "jobName" "host" "type" "closedByControlM" "ticketNumber" "runNo" "notes")
+bhom_slots=("eventType" "alertId" "ctmServer" "fileName" "runId" "severity" "alertStatus" "creation_time" "ctmUser" "updateTime" "msg" "runAs" "subApplication" "application" "jobName" "source_hostname" "alertType" "closedByControlM" "ticketNumber" "runNo" "alertNotes")
+
+# If alert updates are not needed, exit if "call_type" = "U"
+if [ $alert_updates == "N" ] ; then
+   if [ $2 == "U" ] ; then exit 0 ; fi
+fi
+
+# Start JSON and add first BHOM slots
+hctm_tenant=`echo $hctm_url | cut -c 9-`
+json_data="[ { \"class\" : \"$bhom_class\", \"location\" : \"$hctm_name\", \"source_identifier\" : \"$hctm_tenant\""
+
+# Start creating url for the job link
+job_link=$hctm_url/ControlM/#Neighborhood:
+
+# START PROCESSING ALERT DATA
+num_fields=${#alert_fields[@]}
+for (( i=0; i<=$((num_fields-1)); i++ )) ; do
+   field=${alert_fields[$i]}
+   next_field=${alert_fields[$i+1]}
+   if [ $i != $((num_fields-1)) ] ; then
+      value=`echo $* | grep -oP "(?<=\b${field}\b: ).*?(?= \b${next_field}\b:)"`   
+      
+      # Update some fields for BHOM compatibility
+      case $field in
+         server)
+            # Save "server" value in a variable (for the job link)
+            ctm_server=$value
+         ;;
+         runId)
+            # Add "runId" and "server" to the job link
+            job_link=$job_link"id="$value"&ctm="$ctm_server
+         ;;
+         severity)
+            # Convert "severity" format from HCTM to BHOM
+            bhom_severity="sev_${value}"
+            value=${!bhom_severity}
+         ;;
+         time | updateTime)
+            # Convert to Epoch time, in milisecs
+            D="$value"
+            value=`date -d "${D:0:8} ${D:8:2}:${D:10:2}:${D:12:2} +0000" "+%s%3N"`
+         ;;
+         jobName)
+            # Add "jobName" to the final job link
+            job_name="${value// /%20}"  # Replace spaces by "%20"
+            job_link=$job_link"&name="$job_name"&direction=1&radius=3"  # Direction and radius can be customized
+         ;;
+         host)
+            # Save "host" value in a variable (used to determine whether to include the job link)
+            saved_host=$value
+         ;;
+      esac
+
+   else
+      # If last field, capture until EOL
+      value=`echo $* | grep -oP "(?<=\b${field}\b: ).*"`
+   fi
+   slot_name=${bhom_slots[$i]}
+   text=", \"$slot_name\" : \"$value\""
+   json_data=$json_data$text
+done
+
+# Add link to the problematic job (only if "host" was not empty, meaning it is an alert related to a job)
+if [ ! -z "$saved_host" ] ; then
+   json_data=$json_data", \"jobLink\" : \"$job_link\""
+fi      
+
+# Close JSON
+json_data=$json_data" } ]"
+
+# Set library path to solve curl error when Helix Control-M Agent is installed
+# USE ONLY if you get the error: "curl: (48) An unknown option was passed in to libcurl"
+# See https://bmcsites.force.com/casemgmt/sc_KnowledgeArticle?sfdcid=kA33n000000YHinCAG&type=Solution
+# export LD_LIBRARY_PATH="/usr/lib64:$LD_LIBRARY_PATH"
+
+# Send HCTM alert data to BHOM
+curl -X POST $bhom_url -H "Authorization: apiKey $bhom_api_key" -H 'Content-Type: application/json' -d "$json_data"
+
+exit 0