WhatsUp Gold Integration Guide

Pointers

• The integration is between a TaskCall service and WhatsUp Gold.
• This integration only receives alerts in TaskCall from WhatsUp Gold.
• TaskCall will automatically identify alerts that are the same and group them together into one incident.
• Incidents will automatically resolve when devices and monitors are back up in WhatsUp Gold.

In TaskCall

1. Go to Configurations > Integrations and click New Integration.
2. Select the WhatsUp Gold integration.
3. Give the integration a name and configure how incidents will be created. Only the Default Service field is required. The rest are optional.
4. Incidents (Optional)
   1. TaskCall automatically maps incoming payloads with internal attributes to create incidents. However, this can be customized in the Incidents tab. Constant values can be included alongside placeholders to dictate which attributes should map to the Incident Title, Description, Tags, Snapshots and Vendor URL. To insert a placeholder use double curly braces.
      
      
      
      For example, if you enter {{ alert.title }} in the Incident Title field, TaskCall will look for an attribute called "title" nested inside another attribute called "alert" in the incoming payload. If the nested attribute exists, its corresponding value will be pulled from the payload and inserted. If the nested attribute does not resolve successfully, TaskCall will fall back to the default mapping.
      
      If you are unsure, please leave the fields empty. TaskCall will use the default mapping to create the incident for you.
   2. Select the Urgency level the incident should be created at.
   3. Select the option to Group similar alerts together if you would like follow up triggers from the same alert source to be grouped into the same incident. If you leave this option unchecked, then a new incident will be created for every trigger. (This behavior is specific to new triggers; not updates to an alert.)
   4. Click Next to move on to the Services tab.
5. Services (Required)
   1. Select the Default Service incidents should be sent to. To route incidents to different services instead, set Map With Attribute to the attribute to route by using a placeholder. Then, map each value it can take to the service that should receive it.
      
      For example, to route by a region attribute sent in the payload, set Map With Attribute to {{ region }}, then map US to one service and EU to another, and so on.
      
      
   2. Click Next to move on to the Authorization tab.
6. Authorization (Optional)
   1. The Authorization tab allows a Bearer Token and an IP Allowlist be added if you would like to restrict who is able to send alerts to this integration. If you are unsure, this can be skipped.
7. Once done, click Save.
8. Copy the Integration Url that is issued for the integration. This will be used to set up the notification in WhatsUp Gold.

In WhatsUp Gold

The integration requires WhatsUp Gold to send a webhook to TaskCall with alert details. WhatsUp Gold does not allow a webhook to be created natively that has access to alert context. These details have to be logged in a file first. A script then has to be added to read that file and dispatch the webhook. While a single script can handle the process, we will need to create two actions to log the alert details - one for when the device/monitor goes down and one for when it comes back up. Follow through with the steps listed below to configure your account to handle this flow.

1. First, create an action to log changes when devices/monitors go down.
   
   
   1. In WhatsUp Gold, go to Settings > Actions & Alerts > Actions and Policies.
   2. Click the + button under the Actions tab on the modal that opens up to create a new action. Select the Log to Text File action.
      
   3. Complete the action fields:
      • Name the action Trigger Log and give it a description.
      • Set the location for the log file to C:\TaskCall\Logs\action_%Device.HostName.log and the file type to Log(.log).
      • Set the write mode to Overwrite.
      • In the Active and Passive Monitors tab copy and paste the following logging template.
        
        
        alert_status::open;;
        device_active_monitor_down_names::%Device.ActiveMonitorDownNames;;
        device_active_monitor_up_names::%Device.ActiveMonitorUpNames;;
        device_address::%Device.Address;;
        device_database_id::%Device.DatabaseID;;
        device_display_name::%Device.DisplayName;;
        device_host_name::%Device.HostName;;
        device_notes::%Device.Notes;;
        device_role::%Device.Role;;
        device_role_guid::%Device.RoleGUID;;
        device_snmp_oid::%Device.SNMPOid;;
        device_state::%Device.State;;
        device_status::%Device.Status;;
        device_type::%Device.Type;;
        passive_monitor_display_name::%PassiveMonitor.DisplayName;;
        passive_monitor_logged_text::%PassiveMonitor.LoggedText;;
        active_monitor_argument::%ActiveMonitor.Argument;;
        active_monitor_comment::%ActiveMonitor.Comment;;
        active_monitor_name::%ActiveMonitor.Name;;
        active_monitor_network_interface_address::%ActiveMonitor.NetworkInterfaceAddress;;
        active_monitor_payload::%ActiveMonitor.Payload;;
        active_monitor_state::%ActiveMonitor.State;;
        
        
      • Click Save when you are done.

   Test and give log folder permissions

   WhatsUp Gold allows Log to Text actions to be tested from the Actions and Policies screen. Test if the action is executed as expected and the log file is created in the defined location. The folder that we have directed the logs to be written in may not exist in your server and WhatsUp Gold may not have the permissions to create the folder for you. If the test fails because of this then create the folder C:\TaskCall\Logs (and give it the necessary permissions if needed) and test again.

2. Now, create an action to log changes when devices/monitors come back up. Follow through the same steps as above to create an action and set the values as shown below:
   
   
   1. Name the action Resolve Log and give it a description.
   2. Set the location for the log file to C:\TaskCall\Logs\action_%Device.HostName.log and the file type to Log(.log) (same as before).
   3. Set the write mode to Overwrite (same as before).
   4. In the Active and Passive Monitors tab copy and paste the following logging template. (This is almost the same as the trigger log template. Only the value of the alert_status field is different.)
      
      
      alert_status::closed;;
      device_active_monitor_down_names::%Device.ActiveMonitorDownNames;;
      device_active_monitor_up_names::%Device.ActiveMonitorUpNames;;
      device_address::%Device.Address;;
      device_database_id::%Device.DatabaseID;;
      device_display_name::%Device.DisplayName;;
      device_host_name::%Device.HostName;;
      device_notes::%Device.Notes;;
      device_role::%Device.Role;;
      device_role_guid::%Device.RoleGUID;;
      device_snmp_oid::%Device.SNMPOid;;
      device_state::%Device.State;;
      device_status::%Device.Status;;
      device_type::%Device.Type;;
      passive_monitor_display_name::%PassiveMonitor.DisplayName;;
      passive_monitor_logged_text::%PassiveMonitor.LoggedText;;
      active_monitor_argument::%ActiveMonitor.Argument;;
      active_monitor_comment::%ActiveMonitor.Comment;;
      active_monitor_name::%ActiveMonitor.Name;;
      active_monitor_network_interface_address::%ActiveMonitor.NetworkInterfaceAddress;;
      active_monitor_payload::%ActiveMonitor.Payload;;
      active_monitor_state::%ActiveMonitor.State;;



3. With the logging actions in place, now create another action to execute the script that will create the webhook in TaskCall.
   
   
   1. From the choices of actions, select Active Script.
   2. Name the action TaskCall Script and add a description.
   3. Set the script type to JScript and the timeout to 10 seconds.
   4. Copy and paste the following script in the Script Text field. This script parses the log file, compiles it into a JSON format and sends it to TaskCall. Update the < INTEGRATION_URL > field in the script with the integration URL TaskCall generated for you.
      
      
      var TASKCALL_URL = "< INTEGRATION_URL >";
      var logFileLocation = "C:\\TaskCall\\Logs\\action_%Device.HostName.log";
      var fso = new ActiveXObject("Scripting.FileSystemObject");
      var lf = fso.OpenTextFile(logFileLocation, 1, true);
      var attrs = lf.ReadAll().split(";;\n");
      lf.Close();
      var data = {};
      for (i in attrs) {
         var attr = attrs[i];
         var key = attr.split("::", 1);
         var val = attr.replace(/[a-zA-Z_]*::/, "").replace(/;;$/, "");
         data[key] = val;
      }
      // formURLEncodedBody is used to form the URL encoded body for the passed JS Object.
      function formURLEncodedBody(obj) {
         var body = [];
         for (i in obj) {
           body.push(escape(i) + "=" + escape(obj[i]));
         }
         return body.join("&");
      }
      // sendToTaskCall is used to send the alert body to TaskCall
      function sendToTaskCall(tcUrl, body) {
         var strResult = "";
         var returnCode = 0;
         try {
           var WinHttpReq = new ActiveXObject("WinHttp.WinHttpRequest.5.1");
           WinHttpReq.Open("POST", tcUrl, false);
           WinHttpReq.SetRequestHeader("Content-Type", "application/x-www-form-urlencoded");
           WinHttpReq.SetRequestHeader("User-Agent", "TaskCall JScript/1.0 (compatible; Win32; WinHttp.WinHttpRequest.5)");
           WinHttpReq.Send(body);
           strResult = WinHttpReq.ResponseText;
           strResult = "Script executed successfully! : " + strResult;
         } catch (objError) {
           strResult += "WinHTTP returned error: " + (objError.number & 0xFFFF).toString() + "\n\n";
           strResult += objError.description;
           strResult = "Script failed: " + strResult.toString();
         }
         if (this.Context) {
           Context.SetResult(returnCode, strResult);
         } else {
           WScript.Echo("WARNING: The Script is not executed with the WhatsUp Gold Context. Please check your installation.");
           WScript.Echo("ReturnCode: " + returnCode.toString());
           WScript.Echo("Result: ", strResult);
         }
      }
      var reqBody = formURLEncodedBody(data);
      sendToTaskCall(TASKCALL_URL, reqBody);
      
      



4. With the actions defined, now create an action policy that will automatically trigger these actions. The Trigger Log should execute first when the devices/monitors are down, followed by the TaskCall Script action. The Resolve Log should also execute when the devices/monitors are back up, followed by the TaskCall Script action. To set this up, go to the Action Policies tab on the Actions and Policies screen. Click the + button to create a new policy. Give the policy a name like TaskCall Action Policy and add the following policy rules in the exact order shown here:
   
   
   1. Trigger Log - Configure it to execute when the state changes to Down.
   2. TaskCall Script - Configure it to execute when the state changes to Down.
   3. Resolve Log - Configure it to execute when the state changes to Up only if the previous state reached was Down.
   4. TaskCall Script - Configure it to execute when the state changes to Up only if the previous state reached was Down.
   
   
   



5. With the policy saved, now it can be added to the devices for which you want to be notified in TaskCall.
   
   
   1. Navigate to your list of devices. Right click on the name of the device. From the dropdown shown, select Device Properties.
   2. Go to the Actions tab and edit the Device level Actions and Policies and set it to the TaskCall Action Policy you created in the last step.
   
   

And finally you are done! Try simulating a down state in one of the devices you have added the TaskCall Action Policy and ensure that an incident is created in TaskCall. The incident should automatically resolve once the device is back up.