Notification Triggers

Contents

• C#
  • Get
  • Add
  • Modify
  • Remove
  • Types
• PowerShell
  • Get
  • Add
  • Modify
  • Remove
  • Types
• Trigger Channels

C#

PrtgAPI allows you to create and modify notification triggers that have been defined on Sensors, Devices, Groups and Probes. Triggers can be created completely from scratch, or can be derived from existing triggers (allowing you to easily clone triggers across your environment).

Get

All notification triggers that are applied to an object (including any inherited from an objects parent) can be retrieved via the GetNotificationTriggers method.

//Get all notification triggers applied to the object with ID 1234
var triggers = client.GetNotificationTriggers(1234);

All notification trigger types (state, volume, threshold, etc) share a common NotificationTrigger type. NotificationTrigger objects can be further used as templates for creating new triggers and identifying a trigger to modify or remove. For more information, see the Add, Modify and Remove sections below.

Add

Brand new triggers can be defined on objects using the AddNotificationTrigger method. Due to the number of fields that can be defined on notification triggers across the variety of notification trigger types, in order to add (or modify) a notification trigger a TriggerParameters object must be defined.

PrtgAPI defines the following trigger parameter types for each type of notification trigger supported by PRTG

• StateTriggerParameters
• ChangeTriggerParameters
• SpeedTriggerParameters
• VolumeTriggerParameters
• ThresholdTriggerParameters

Each type defines several constructors for either adding or editing a notification trigger.

Triggers can be created from scratch

//Create a new state notification trigger and add it to the object with ID 1001.
//StateTriggerParameters have default properties that mirror those in the PRTG UI:
//Trigger state is "Down" while Latency and EscalationLatency are 60 and 300 seconds
//respectively. All other properties are null or 0
var parameters = new StateTriggerParameters(1001)
{
    Latency = 40
};

var trigger = client.AddNotificationTrigger(parameters);

Or can be based on an existing trigger

//Add a new threshold trigger using the settings of an existing trigger,
//setting the OnNotificationAction to be the "Ticket Notification" action

//Get the first threshold trigger defined on the object with ID 1001
var trigger = client.GetNotificationTriggers(1001).First(t => t.Type == TriggerType.Threshold);

//Get the "Ticket Notification" NotificationAction
var action = client.GetNotificationAction("Ticket Notification");

//Create a new set of threshold trigger parameters for applying a threshold trigger on the
//object with ID 2002 using the settings of an existing notification trigger
var parameters = new ThresholdTriggerParameters(2002, trigger)
{
    OnNotificationAction = action
};

//Add the trigger to the target object
var newTrigger = client.AddNotificationTrigger(parameters);

Not all objects support all notification trigger types. When a new notification trigger is added, PrtgAPI will automatically perform a lookup against the target object to determine the notification trigger types that are supported. If the specified trigger type is not applicable, an InvalidTriggerTypeException will be thrown listing the types that are supported. Special rules apply when creating notification triggers that contain Channel properties. For more information, see Trigger Channels below.

By default PrtgAPI will resolve any new triggers to their resultant NotificationTrigger objects. As PRTG does not return any information about the created trigger, PrtgAPI uses a diff based resolution mechanism to identify the newly created object. In the event an identical trigger is created under the specified parent object while resolution is occurring, PrtgAPI will throw an ObjectResolutionException specifying the OnNotificationAction of the triggers found. If you do not wish to perform object resolution, this behavior can be disabled by setting the optional parameter resolve to false. If object resolution is disabled, AddNotificationTrigger will return null.

//Add a new trigger without resolving it
client.AddNotificationTrigger(parameters, false);

Modify

Note: for information on modifying whether notification triggers are inherited by a given device, group or probe, please see the Remove section below

Notification Triggers can be manipulated via the SetTriggerProperty method

//Set the OnNotificationAction of a notification trigger to "Ticket Notification"
var action = client.GetNotificationAction("Ticket Notification");
client.SetTriggerProperty(trigger, TriggerProperty.OnNotificationAction, action);

The SetTriggerPropery method functions identically to the SetObjectProperty and SetChannelProperty methods, used for modifying general and Channel objects respectively. Multiple properties can be modified at once by specifying an array of TriggerParameter objects

client.SetTriggerProperty(
    trigger,
    new TriggerParameter(TriggerProperty.OnNotificationAction, action),
    new TriggerParameter(TriggerProperty.Latency, 40)
);

As the underlying API for creating and modifying Notification Triggers is quite similar, PrtgAPI also allows you to modify Notification Triggers by passing a TriggerParameters object to the SetNotificationTrigger method. When constructing a TriggerParameters object for modifying an existing trigger, by default all parameter properties will be null. Any properties that are assigned a value will overwrite the existing properties of the trigger.

//Set the latency of a state notification trigger on the object with ID 1001 to 40 seconds
var trigger = client.GetNotificationTriggers(1001).First(t => t.Type == TriggerType.State);

var parameters = new StateTriggerParameters(trigger)
{
    Latency = 40
};

client.SetNotificationTrigger(parameters);

Any trigger parameter property that has been assigned a value can be assigned null to remove that property and prevent it from being modified when the modification request is executed. NotificationAction properties (including OnNotificationAction, OffNotificationAction and EscalationNotificationAction) can be explicitly assigned null to set their actions to the "None" notification action.

//Remove the "on trigger activated" notification action applied to a trigger
var parameters = new SpeedTriggerParameters(trigger)
{
    OnNotificationAction = null
};

client.SetNotificationTrigger(parameters);

As notification action properties treat explicit assignment of null differently to other properties, once a notification action has been assigned null it is not possible to remove a value from this property without creating a new TriggerParameters object.

For safety, PrtgAPI will prevent you from modifying a trigger that has been inherited from another object. This restriction can be bypassed using the constructor overload taking an ObjectId and a SubId.

//Modify an inherited notification trigger
var parameters = new StateTriggerParameters(trigger.ParentId, trigger.SubId);

Remove

Notification triggers can be removed from an object using the RemoveNotificationTrigger method

//Remove all notification triggers on the object with ID 1001
var triggers = client.GetNotificationTriggers(1001).Where(t => t.Inherited == false);

foreach(var trigger in triggers)
{
    client.RemoveNotificationTrigger(trigger);
}

RemoveNotificationTrigger does not support removing triggers that are inherited from a parent object. Attempting to remove an inherited notification trigger will cause an InvalidOperationException to be thrown. To remove inherited triggers, retrieve them from their parent objects identified by the ParentId property, or alternatively disable notification trigger inheritance on the specified object by setting its InheritTriggers property to false. In the case of sensors, notification trigger inheritance should be disabled on the parent device instead. For more information on modifying object properties please see Property Manipulation.

//Disable trigger inheritance on the device, group or probe with ID 1001
client.SetObjectProperty(1001, ObjectProperty.InheritTriggers, false);

Types

When attempting to add a new notification trigger to an object, PrtgAPI will automatically attempt to validate that the specified trigger type is applicable to the target object. Trigger types supported by an object can be separately viewed via the GetNotificationTriggerTypes method

//Get a list of all trigger types supported by the object with ID 1001
var types = client.GetNotificationTriggerTypes(1001);

PowerShell

PrtgAPI provides a variety of cmdlets for interacting with notification triggers. All cmdlets whose names begin with NotificationTrigger can also be referred to via a shortened name, simply containing Trigger; i.e. Get-NotificationTrigger can also be invoked as simply Get-Trigger

Get

Notification triggers that have been applied to an object can be retrieved via the Get-NotificationTrigger cmdlet

C:\> Get-Probe | Get-NotificationTrigger

Type        ObjectId SubId Inherited ParentId Latency Condition Threshold Unit       OnNotificationAction
----        -------- ----- --------- -------- ------- --------- --------- ----       --------------------
Change      1        8     False     1                Change                         Ticket Notification
State       1        1     True      0        600     Equals    Down                 Email Administrator
Threshold   1        7     False     1        60      NotEquals 5                    Email PRTG Alerts Mailbox
Speed       1        5     False     1        60      Above     3         TByte/Day  SMS Escalation Team 1
Volume      1        6     False     1                Equals    6         KByte/Hour SMS Escalation Team 1

Get-NotificationTrigger provides a variety of parameters for easy filtering of triggers, including excluding triggers that are -Inherited as well as filtering for triggers of a specific -Type

# Get all state triggers that have explicitly been defined on devices named "dc-1"
Get-Device dc-1 | Get-Trigger -Inherited $false -Type State

Notification triggers can be filtered by any of their properties, such as their OnNotificationAction

# Get all notification triggers on all probes whose OnNotificationAction contains "ticket"
Get-Probe | Get-Trigger *ticket*

Add

PrtgAPI supports two different styles of adding new Notification Triggers to object

• PowerShell style, by defining the parameters of the sensor inline using the New-Trigger cmdlet
• C# style, by creating a TriggerParameters object to be added with Add-NotificationTrigger

Note that technically speaking New-Trigger and Add-NotificationTrigger are the same cmdlet; as such you may use the names interchangeably. Both names are simply provided to ensure consistency with standard PowerShell naming and the naming PrtgAPI uses for its C# interface.

PowerShell Style

New Notification Triggers can be created and added in a single line via the New-Trigger cmdlet

# Add a new State Notification Trigger using the "Ticket Notification"
# Notification Action to all probes
Get-Probe | New-Trigger -Type State -OnNotificationAction *ticket* -Latency 40

Like Set-TriggerProperty, values that accept either a NotificationAction or TriggerChannel can alternatively specify a wildcard value. If the specified wildcard is ambiguous (or no matches were found), New-Trigger will throw an exception specifying the reason for the failure. This eliminates the need to call Get-NotificationAction and Get-Channel manually, allowing for new Notification Triggers to be created via one-liners.

If a parameter is used with in compatible trigger type (such as specifying a -Channel with a State trigger) PrtgAPI will throw an exception indicating that the parameter is incompatible.

C# Style

Notification Triggers can also be created by defining a TriggerParameters object and passing it to the Add-NotificationTrigger cmdlet. TriggerParameters objects can be created with the New-TriggerParameters cmdlet

# Create a set of trigger parameters for creating a state trigger on the Object with ID 1001
$params = New-TriggerParameters 1001 State

# Create a set of trigger parameters via a piped object
$params = Get-Device -Id 1001 | New-TriggerParameters State

C:\> $params

OffNotificationAction        : None
EscalationNotificationAction : None
Latency                      : 60
EscalationLatency            : 300
RepeatInterval               : 0
State                        : Down
ObjectId                     : 1001
SubId                        :
Action                       : Add
Type                         : State
OnNotificationAction         : None

Based on the type of notification trigger specified, New-TriggerParameters will return a TriggerParameters object specific to the trigger type. The following trigger types are supported

• Change
• State
• Speed
• Volume
• Threshold

TriggerParameters object properties will default to the default values found when adding the specified trigger type within the PRTG UI. After editing any properties the trigger can then be added.

# Set the OnNotificationAction to the "Ticket Notification" action, then add the trigger

C:\> $params.OnNotificationAction = Get-NotificationAction "Ticket Notification"
C:\> $params | Add-Trigger

Type        ObjectId SubId Inherited ParentId Latency Condition Threshold Units      OnNotificationAction
----        -------- ----- --------- -------- ------- --------- --------- -----      --------------------
Change      1        8     False     1                Change                         Ticket Notification

Special rules apply when creating notification triggers that contain Channel properties. For more information, see Trigger Channels below.

By default, Add-NotificationTrigger will attempt to resolve the created trigger to its resultant NotificationTrigger object. While this is generally very reliable, in the event something or someone else creates another new trigger with the same name OnNotificationAction under the parent device in the time period between the first and second diff, that object will also be returned in objects returned by Add-NotificationTrigger. If you do not wish to retrieve the created trigger, you can disable this functionality by specifying -Resolve:$false.

TriggerParameters can also be created from existing NotificationTrigger objects, for scenarios in which you either wish to directly clone an existing trigger to another object, or scenarios in which you wish to use an existing trigger as a "template" for a new trigger you are trying to create.

# Clone all state triggers from the sensor with ID 1001 to the object with ID 1234
Get-Sensor -Id 1001 | Get-Trigger -Type State -Inherited $false | New-TriggerParameters 1234 | Add-Trigger

For scenarios in which you don't wish to modify the TriggerParameters created from an existing trigger, you can also use the Clone-Object cmdlet to automatically create the required TriggerParameters and add the object for you.

Get-Sensor -Id 1001 | Get-Trigger -Type State -Inherited $false | Clone-Object 1234

Modify

Note: for information on modifying whether notification triggers are inherited by a given device, group or probe, please see the Remove section below

PrtgAPI provides two cmdlets for modifying existing notification triggers. For scenarios in which you wish to modify a single notification trigger property, the Set-NotificationTriggerProperty cmdlet can be used

# Set the latency of all state notification triggers applied to probes to 40 seconds

$triggers = Get-Probe | Get-Trigger -Inherited $false -Type State
$triggers | Set-TriggerProperty Latency 40

For safety, PrtgAPI will prevent you from modifying a trigger that has been inherited from another object. To modify any inherited triggers, retrieve them from their parent objects. The parent object of a trigger is identified by its ParentId property.

Multiple properties can be modified at once by specifying one or more dynamic cmdlet parameters

$triggers | Set-TriggerProperty -Latency 40 -OnNotificationAction *ticket*

When modifying the value of the OnNotificationAction, OffNotificationAction, EscalationNotificationAction or Channel, if a wildcard value is specified, Set-TriggerProperty will attempt to resolve the specified value for you, eliminating the need to acquire the required objects yourself (via the Get-NotificationAction and Get-Channel cmdlets respectively)

Like the C# API, you can alternatively modify notification trigger properties using the Set-NotificationTrigger cmdlet in conjunction with a set of TriggerParameters

$params = Get-Probe | Get-Trigger -Inherited $false -Type Threshold | New-TriggerParameters
$params.OnNotificationAction = $null
$params.Latency = 30

$params | Set-NotificationTrigger

Any trigger parameter property that has been assigned a value can be assigned $null to remove that property and prevent it from being modified when the modification request is executed. NotificationAction properties (including OnNotificationAction, OffNotificationAction and EscalationNotificationAction) can be explicitly assigned $null to set their actions to the "None" notification action.

As notification action properties treat explicit assignment of $null differently to other properties, once a notification action has been assigned $null it is not possible to remove a value from this property without creating a new TriggerParameters object.

The Set-NotificationTriggerProperty cmdlet is capable of executing in PassThru Mode. For more information on PassThru Mode, see PassThru Requests.

Remove

Notification triggers can be removed from objects using the Remove-NotificationTrigger cmdlet

Get-Probe | Get-Trigger *ticket* | Remove-Trigger

When removing a trigger, PrtgAPI will prompt you to confirm whether you are sure you want to remove the specified trigger. When removing multiple triggers it is recommended to first run Remove-NotificationTrigger with -WhatIf to get a list of all triggers that will be removed. Remove-NotificationTrigger can then be executed with -Force to bypass the confirmation prompt.

Triggers that have been inherited from another object cannot be removed. To remove inherited triggers, retrieve them from their parent objects identified by the ParentId property, or alternatively disable notification trigger inheritance on the specified object by setting its InheritTriggers property to $false. In the case of sensors, notification trigger inheritance should be disabled on the parent device instead. For more information on modifying object properties please see Property Manipulation.

# Disable trigger inheritance on the device with ID 1001
Get-Device -Id 1001 | Set-ObjectProperty -InheritTriggers $false

Types

When attempting to add a new notification trigger to an object, PrtgAPI will automatically attempt to validate that the specified trigger type is applicable to the target object. Trigger types supported by an object can be separately viewed by specifying the -Types parameter to Get-NotificationTrigger

C:\> Get-Sensor "disk io*" | Get-Trigger -Types

Name              ObjectId  State  Speed  Volume  Threshold  Change
----              --------  -----  -----  ------  ---------  ------
Disk IO _Total    2001      True   False  False   True       False

Trigger Channels

Certain trigger types (including Threshold, Speed and Volume) support specifying specific channels that should be used to alert on. When a trigger is defined on a container object (Device, Group or Probe) PRTG supports specifying high level identifiers, including the following

• Primary (the sensor's primary channel)
• Total (the sensor's Total channel (if applicable))
• TrafficIn (the sensor's TrafficIn channel (if applicable))
• TrafficOut (the sensor's TrafficOut channel (if applicable))

When a notification trigger is applied directly to a sensor, PRTG requires that any channels specified refer to an actual channel defined on the object. PrtgAPI models this functionality via the TriggerChannel type. The TriggerChannel type is like an enum on steroids. In C#, TriggerChannel defines static members that correspond to each of the trigger channel types applicable to container objects

//C#
var parameters = new SpeedTriggerParameters(1001)
{
    Channel = TriggerChannel.Primary
};

In PowerShell, you can simply specify a string (as you would a regular enum) and PowerShell will coerce the value for you

# PowerShell
$params = New-TriggerParameters 1001 Speed
$params.Channel = "Primary"

For notification triggers that are applied directly to sensors, a Channel object must be specified, which can be achieved via an implicit cast

//C#
var channel = client.GetChannel(1001, "Percent Available Memory");

var parameters = new SpeedTriggerParameters(1001)
{
    Channel = channel
};

# PowerShell
$channel = Get-Sensor -Id 1001 | Get-Channel "Percent Available Memory"

$params = New-TriggerParameters 1001 Speed
$params.Channel = $channel

When a notification trigger containing a TriggerChannel is added or modified, PrtgAPI will automatically validate whether the specified channel is applicable to the target object. If the specified channel is not applicable, an InvalidOperationException will be thrown.

See Also

• Notification Actions
• Channels
• Sensors
• Devices
• Groups
• Probes
• Objects
• Filters