Customizing alert scripts

Alert scripts can handle up to 22 dimensions and metrics that can be passed from a NAM alert to an alert script as parameter values.

The following dimensions and metrics are available on the report server for alert scripting:

  • {1} - Tier
  • {2} - Application
  • {3} - Transaction
  • {4} - Reporting group
  • {5} - Software service
  • {6} - Server IP address
  • {7} - Server DNS name
  • {8} - Operation
  • {9} - Task
  • {10} - Module
  • {11} - Service
  • {12} - Step
  • {13} - Site
  • {14} - Area
  • {15} - Region
  • {16} - WAN Link
  • {17} - Metric value
  • {18} - Unit of measure
  • {19} - Threshold
  • {20} - Auxiliary metric value
  • {21} - Auxiliary unit of measure
  • {22} - Alert triggering mode

and additional parameters specific to the alert process and delivery:

Note

Some of the parameters are stand-alone while others accept a value in the form of a reference to the given field number. Places requiring such a reference are indicated by round brackets “()”

{notificationMessage}

Passes the notification message.

{propagationMessage}

Passes the propagation message.

{getIPAddress()}

Normalize IP address: accepts a reference to an IP address field in the alarm template, and returns an IPv4 dotted quad.

{urlHostBase}

Passes the report server URL.

{sTS}

Passes the time stamp of the start of the last monitoring interval for Software service, operation, and site data (zdata). Note that a timestamp is expressed as a number and not as a date/time string.

{encodeURL()}

Encode the given field in the alarm template, such as a URL, to replace special characters (for example, spaces) using %-denoted escape sequences.

{eTSzdata}

Passes the timestamp of the end of the last monitoring interval for Software service, operation, and site data (zdata). Note that a timestamp is expressed as a number and not as a date/time string.

{getDate()}

Translates a reference to a timestamp field to a date and time string.

{eTStransdata}

Returns the timestamp of the start of the monitoring interval for Synthetic and sequence transaction data (transdata). Note that a timestamp is expressed as a number and not as a date/time string.

{samplingInterval}

Passes the length of the monitoring interval, expressed in minutes.

Pass the parameters to the script in the Add Script Recipient parameter window:

-message '{notificationMessage}'
–application '{2}'
-operation '{3}'
–threshold '{4}'

In your PowerShell script, define the parameters that the script will receive from the triggered alert:

param (
  [string]$message = "",
  [string]$application = "",
  [string]$operation = "",
  [string]$threshold = "",  
    ...
)

If you are using the PowersShell script to interact with ServiceNow service desk platform, make sure that your script contains a parameter for the ServiceNow location, and parameters for your ServiceNow user name and password, aside from the typical parameters that you want to pass to the script.

-service_now_uri 'https://my-instance.service-now.com/imp_notification.do?SOAP'
-service_now_user_name 'sam.adams'
-service_now_password 'secretpass'

Your script would also then include definitions for these parameters:

param (
  [string]$message = "",
  [string]$application = "",
  [string]$operation = "",
  [string]$threshold = "",  
    ...  
  [string]$service_now_uri = "",  
  [string]$service_now_user_name = "",  
  [string]$service_now_password = ""
)

Because ServiceNow uses the SOAP transport protocol, you can modify the XML SOAP request in your script in order to achieve different ServiceNow incident reporting. The example creates a ServiceNow incident that is Category 'Network ', state 'New ', severity '1 ', and the incident report source is 'DCRUM '.

 $SN_xml = [xml]@"
<?xml version="1.0"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:imp="http://www.service-now.com/imp_notification">
   <soapenv:Header/>
   <soapenv:Body>
      <imp:insert>
         <category>Network</category>
         <comments></comments>
         <message></message>
         <severity>1</severity>
         <source>DCRUM</source>
         <state>New</state>
         <timestamp></timestamp>
         <uuid></uuid>
      </imp:insert>
   </soapenv:Body>
</soapenv:Envelope>
"@

The default configuration of notification import service contains following fields and mappings that can be passed in the SOAP message:

Source field - assignment_group, category, comments, duration, message, severity, source, state, uuid
Target Field - assignment_group, category, comments, calendar_duration, short_description, severity, cmdb_ci, incident_state, correlation_id

Customizing the XML SOAP message in your script enables you to have more control over how the incident is reported in ServiceNow. For example, you can control the severity value based on the category and duration value.