Alarm actions allow you react to an alarm.  You can configure an action to run when a specific Alarm Level threshold is crossed.

You can configure actions for the Default Alarms for a resource group and for individual resources.

To add an action to an Alarm:

1.Open Settings, then select a resource group or individual resource, and click the Alarms tab.

2.Click the down caret next to the alarm you want to configure.

3.Click Add Action to add a new action to the alarm.

You can only add actions if the Alarm has one or more Alarm Levels and there are one or more scripts available on the hub server.

4.Select the Alarm Level that this action will react to.

5.Choose whether the action should execute when the threshold is entered or exited.

6.Select the script that will run for this action.

7.Click the check icon to save the action.

The action will not execute immediately. It will trigger the next time its criteria for execution are met.  This may require the Alarm to exit the Alarm Level's threshold first before it can enter the state again.

Actions may run in any order and can execute concurrently.

Actions are tied to a specific Alarm Level of an Alarm.  This means that if the value of an alarm causes multiple alarm levels to transition state and each Alarm Level has an action, all actions for all Alarm Levels that transitioned will execute. That is, if both an "Info" and "Warning" alarm level are crossed, actions for both Alarm Levels will execute regardless of the resulting alarm state, which would indicate a warning.

Updating an Alarm's Alarm Levels resets the state of the Alarm and clears the Alarm Levels. This will trigger any actions configured to execute when the alarm level exits its state.

Analytics will only wait 10 seconds for an action to complete before moving on.  The action will continue running, but Analytics will no longer track its status or know if it fails

Test an Alarm Action

You can test an action configured on an Alarm or an action that is being added to an alarm.  To do this, click Test  in the row of the action you want to test.

You can test actions on an individual resource or for a resource group.  If testing an action for a resource group, default placeholder information is provided to the action for the resource information and the current value will be null.

The action will execute in full.  If your script performs actions like sending emails, rebooting servers, modifying files, or logging information, those actions will occur when you test an action.

Scripts as Actions

An alarm action can be either a PowerShell or Batch script that will execute on the hub server.

We recommend using PowerShell as it offers more capabilities and is more flexible.  Batch scripts are supported for running pre-existing scripts that have not been migrated to PowerShell.

Scripts must complete in two minutes.  If they exceed this limit, they will be terminated.

Add Scripts to the Hub Server

For security reasons, Analytics does not allow you to upload scripts through its UI.  You must have access to the Hub server to add scripts that Analytics can execute as Alarm actions.

The directory for scripts is C:\ProgramData\VertiGIS Studio Analytics\hub\.data\custom-scripts\metrics\

You can create subfolders to organize your scripts, but we recommend keeping the structure one or two levels deep to keep the path short.

Analytics will not execute scripts from outside of this folder for security reasons.  However, scripts within this folder can reference scripts from other locations. Referenced scripts will be executed as Analytics has no knowledge of the executing script contents or references.

For security purposes, we recommended that only Administrators and the 'NT Service\VertiGIS Studio Analytics - Hub' user have access to this folder.

Arguments Passed to Scripts

 

PowerShell Scripts

PowerShell allows for named parameters.  To access the named parameters from the arguments passed by Analytics use something similar to the following in your script (the output line is to show how to use the parameter and is not necessary in your script).

param(

 [string]$name,

 [string]$currentState,

 [string]$currentValue,

 [string]$thresholdState,

 [string]$thresholdOperator,

 [string]$thresholdValue,

 [string]$thresholdTriggerOccurrences,

 [string]$resourceName,

 [string]$resourceType

)

Write-Output "Metric name: $name"

 

Email PowerShell Script Example

The following example uses the Send-MailMessage command in PowerShell, which is obsolete.  See this Microsoft article for more information. We use this command as an example because it does not require any additional libraries. However, we do not recommend it for production use.  Instead, there are other third-party options recommended by Microsoft. Or, consider using Send-MgUserMail from Microsoft Graph PowerShell SDK.

param(

 [string]$name,

 [string]$currentState,

 [string]$currentValue,

 [string]$thresholdState,

 [string]$thresholdValue,

 [string]$resourceName,

 [string]$resourceType

)

 

$sendMailMessageSplat = @{

   From = 'VertiGIS Studio Analytics <myUser@myDomain.com>'

   To = 'Analytics Group <myAnalyticsGroup@myDomain.com>'

   Subject = "VertiGIS Studio Analytics Alarm - $currentState - $name - $resourceName"

  Body = @"

VertiGIS Studio Analytics Alarm

$name

$resourceName

$resourceType

$thresholdState

Value: $currentValue

Threshold: $thresholdValue

Current State: $currentState

"@

   SmtpServer = 'mySmtpServer.com'  

}

Send-MailMessage @sendMailMessageSplat

 

Batch Scripts

Batch scripts do not support named parameters, but we pass arguments to Batch scripts with named parameters.  To extract the arguments, you can use the following script.

The last ECHO line shows you how to use an argument and is not necessary in your script.

@ECHO OFF

setlocal enableDelayedExpansion

set "prev="

set "current="

for %%a in (%*) do (

 set "current=%%~a"

 if  defined prev (

   set "!prev!=%%~a"

   set "prev="

 ) else (

   set prev=%%a

 )

)

ECHO Metric name: %-name%

 

Troubleshooting Scripts

Alarm actions for individual resources indicate the last time they ran and if they encountered any errors.

If a script fails at runtime, any errors or output (stdout, stderr) are written to the Analytics hub-metrics log file.

You can find the hub log files at C:\ProgramData\VertiGIS Studio Analytics\hub\.data\logs.

To test your script as if an Alarm Level has transitioned state, use the Test button for the Alarm Action.

If you use the Test button to test an action and the script fails, any errors or output (stdout, stderr) are written to the Analytics hub-server log file.

Testing an action with a script will execute the script in full.  If your script performs actions like sending emails, rebooting servers, modifying files, or logging information, those actions will occur when you test the script.