WhatsUp Gold Integration Guide

WhatsUp Gold provides a unified view and fully encompasses heterogeneous environments and vendors so you can see everything on your network. Improve your network performance and improve uptime throughout today’s diverse networks by monitoring and analyzing everything from one actionable, unified dashboard.

This integration works by logging WhatsUp Gold alerts to a file containing JSON formatted for our Events API. A VBScript then iterates through every file in the queue directory where alerts are written to and sends the JSON to PagerDuty, deleting the alert file after it has been accepted by the server.

Compatibility

This guide and VBScript were written and tested on Windows Server 2012 R2 with WhatsUp Gold 2017. Earlier versions of WhatsUp Gold which do not support logging alerts to a file in the required format can be configured to send alerts to PagerDuty using an email integration instead.

In PagerDuty

1. Navigate to Services → Service Directory
2. On the Services page:
   • If you are creating a new service for your integration, click Add New Service.
   • If you are adding your integration to an existing service, click the name of the service you want to add the integration to. Then click the Integrations tab and click the Add a new integration link.
3. Select your app from the Integration Type menu and enter an Integration Name.If you are creating a new service for your integration, in General Settings, enter a Name for your new service. Then, in Incident Settings, specify the Escalation Policy, Notification Urgency, and Incident Behavior for your new service.
4. Click the Add Service or Add Integration button to save your new integration. You will be redirected to the Integrations page for your service.
5. Copy the Integration Key for your new integration.

On Your WhatsUp Gold Server

1. Create the following directories on your WhatsUp Gold server's C: drive:
   • C:\PagerDuty
   • C:\PagerDuty\Queue
2. Download the following VBScript, saving it to C:\PagerDuty on your WhatsUp Gold server.
   • PagerDuty.vbs
3. Log in to the WhatsUp Gold web interface as an admin, then go to Settings → Actions & Alerts → Actions and Policies.
4. Create a new Log To Text File action in the Action Library.
5. Give the new action a Name such as "Log Alert to PagerDuty Queue", set the Log file path to C:\PagerDuty\Queue\%Device.HostName_Down.txt, change the Log file write mode to Overwrite, then copy and paste the following into the Log Message field:

   {
     "service_key": "YOUR-INTEGRATION-KEY-HERE",
     "incident_key": "%Device.Address Monitors Down",
     "event_type": "trigger",
     "description": "%Device.ActiveMonitorDownNames %Device.State on %Device.HostName",
     "details": {
       "Monitors that are down": "%Device.ActiveMonitorDownNames",
       "Monitors that are up": "%Device.ActiveMonitorUpNames",
       "Host Name": "%Device.HostName",
       "IP Address": "%Device.Address"
     }
   }

   Be sure to replace YOUR-INTEGRATION-KEY-HERE with the PagerDuty integration key you created earlier.
6. Create another new Log To Text File action in the Action Library. Give this new action a Name such as "Log Recovery to PagerDuty Queue", set the Log file path to C:\PagerDuty\Queue\%Device.HostName_Up.txt, change the Log file write mode to Overwrite, then copy and paste the following into the Log Message field:

   {
                 "service_key": "YOUR-INTEGRATION-KEY-HERE",
                 "incident_key": "%Device.Address Monitors Down",
                 "event_type": "resolve",
                 "description": "%Device.ActiveMonitorDownNames %Device.State on %Device.HostName"
               }

   Be sure to replace YOUR-INTEGRATION-KEY-HERE with the PagerDuty integration key you created earlier.
7. Create a new Program Action and give the new action a Name such as "Execute PagerDuty VBScript", set the Program file name to C:\Windows\System32\cscript.exe, the Working path to C:\PagerDuty, and the Program arguments to //B "C:\PagerDuty\PagerDuty.vbs".
8. Create a new Action Policy and give it a Name such as "PagerDuty" (or edit an existing policy already in use by the devices you want to start triggering alerts for in PagerDuty) then add the PagerDuty actions you created for both Up and Down states. The Log Alert action should be performed for the Down state, and the Log Recovery action should be performed for the Up state, while the Program Action (VBScript execution) should be performed for both states, but after the Log Alert or Log Recovery action has been performed.
9. Configure your devices to use this Action Policy by going to My Network, selecting a device, and clicking Monitor setup. Go to the Actions and Action Policies tab and select Apply the following Action Policy, then choose the Action Policy you created or updated in the previous step.
10. Open Windows Task Scheduler and click Create Task... on the Actions sidebar. Give the task a Name, like PagerDuty, and select Run whether user is logged in or not.
11. Switch to the Triggers tab and click New..., then click the drop down list for Begin the task and select At startup. Now check the box labeled Repeat task every: and type in 1 minute (this option isn't in the list, you must manually type it in), then change the duration to Indefinitely and click OK. Repeat these steps, only selecting At task creation/modification the second time around.
12. Select the Actions tab and click New.... Set the Program/script to C:\Windows\System32\cscript.exe and Add arguments to //B "C:\PagerDuty\PagerDuty.vbs", then click OK.
13. Click OK.
14. Congratulations! WhatsUp Gold will now be able to trigger and resolve incidents in PagerDuty, and the scheduled task will re-try sending events in case they aren't successfully sent in the first attempt (i.e. due to connectivity issues).

Customizing Your Alerts

You can customize the alert data sent to PagerDuty by changing the Log Message in your Log To Text File action. The file should be logged to C:\PagerDuty\Queue with a .txt file extension, and the content should be JSON that is formatted for our Events API. Special Characters: If you have an alert which uses characters that will affect the JSON output, such as a quotation mark, then you will need to escape those characters with a backslash, or modify the VBScript to handle them. For example, if you add quotation marks to an alert, add a backslash (\) before them so they look like \" in your Log To Text File action. Other special characters can be escaped if needed by modifying the VBScript and using the Replace method, which is what we use in the script to escape backslashes, as backslashes have a special purpose in JSON as the escape character, but are also used in alerts containing Windows paths. Lastly, you'll want to make sure there is a Program Action configured that executes "C:\PagerDuty\PagerDuty.vbs" using the CScript.exe interpreter. This allows WhatsUp Gold to send the alert to PagerDuty immediately, rather than having to wait for the scheduled task to run before it gets sent to us.

FAQ

Can I trigger incidents on multiple PagerDuty services?

Yes. Simply duplicate your Log To Text File actions and modify them to use a different PagerDuty integration key, create a new Action Policy that uses these new actions, then configure the desired devices to use this alternate Action Policy.

I'm not receiving alerts in PagerDuty. How can I check for errors?

The VBScript will log errors to the Windows Application Event Log to help resolve problems with alerts not being sent to PagerDuty. You can also manually execute the VBScript via Command Prompt using CScript.exe "C:\PagerDuty\PagerDuty.vbs" to see what happens to alert files in the queue step-by-step.

Can I put the VBScript and write alert files somewhere other than C:\PagerDuty?

If you would like the VBScript and alert queue directory to reside somewhere other than C:\PagerDuty, you will need to modify the QueuePath variable in the VBScript from C:\PagerDuty\Queue to point to the location where you would like the alert queue to reside.

Can I write alerts to or run the VBScript from a shared folder or mapped network drive (i.e. to use with multiple WhatsUp Gold servers)?

Although the VBScript can be executed from a shared folder or mapped network drive, we recommend using a local copy and alert queue on each system in case the host with the script becomes unavailable. For example, if you configure WhatsUp Gold to write alerts to a queue on a file server and execute the VBScript hosted on that server, and that server goes down for any reason, WhatsUp Gold will not be able to write alert files or execute the VBScript to trigger an incident in PagerDuty for any WhatsUp Gold alerts until the file server is available again.

What if a WhatsUp Gold alert is generated while my network is down?

If PagerDuty can’t be reached for any reason, events will be stored in C:\PagerDuty\Queue. The scheduled task to execute the VBScript will attempt to re-send the events at one minute intervals, so your WhatsUp Gold server should begin sending incidents to PagerDuty within a minute of being able to access the internet again.