-
-
Notifications
You must be signed in to change notification settings - Fork 39
Property Manipulation
PrtgAPI enables retrieving and modifying the properties and settings of sensors, devices, groups, probes and channels in a type safe, reliable manner. PrtgAPI is capable of retrieving all properties of an object and displaying them all at once. For properties not currently supported by PrtgAPI, these properties can still be interacted with via their raw property names.
To view a list of all properties currently supported by PrtgAPI, please install the PowerShell version of PrtgAPI and run one of the following commands, or alternatively click the link on the command to view the online version
Sensor, Device, Group and Probe properties can be retrieved from PRTG using each of their respective Get<object>Properties
methods
//Retrieve all sensor properties
var sensorSettings = client.GetSensorProperties(1001);
//Retrieve all device properties
var deviceProperties = client.GetDeviceProperties(1002);
Either can object ID or existing object reference can be specified
//Retrieve sensor properties for an existing sensor object
var sensorSettings = client.GetSensorProperties(sensor);
Certain properties are considered "read-only" when you view them on the Settings page in PRTG. PrtgAPI will endeavor to return these anyway in requests for object properties, and these properties can also be retrieved by asking for them directly.
//Retrieve the SQL Server Query file of a Microsoft SQL v2 sensor
var query = client.GetObjectProperty(1001, ObjectProperty.SqlServerQuery);
Values returned by GetObjectProperty
will always be of their true type, as seen in the
members of the SensorSettings
/DeviceSettings
/GroupSettings
/ProbeSettings
types returned by Get<object>Properties
. If you know the true type of the value you are retrieving, you can instead call GetObjectProperty<T>
to have PrtgAPI cast the returned value for you. Attempting to cast a value to an invalid type will generate an exception stating the actual type that was expected.
// InvalidCastException! SensorSettings.HttpRequestMethod
// defines this value as being of type HttpRequestMethod?
var method = client.GetObjectProperty<bool>(2002, ObjectProperty.HttpRequestMethod)
When retrieving individual object properties, please note that if your PRTG server is not in English and you attempt to retrieve an individual property that does not exist on the target object, due to limitations of the PRTG API you may receive a deserialization error or the string "(Property does not exist)" in your server's native language.
Note due to the way PrtgAPI retrieves object properties, pluralized property methods (GetSensorProperties
, etc) will throw an InvalidOperationException
if the current PRTG user has read-only access to the specified object. Singular property methods (GetObjectProperty
) can always be used regardless of whether the current user has read or write access.
Channel objects do not have a separate method for retrieving their properties, as these details are included in the standard channel response. For more information on retrieving channels, please see Channels.
Properties for all supported first class object types can be modified using the SetObjectProperty
method.
//Change the Windows Domain of the device with ID 1001 to "contoso"
client.SetObjectProperty(1001, ObjectProperty.WindowsDomain, "contoso");
As is the case when retrieving properties, Either can object ID or existing object reference can be specified
//Change the Windows Domain a given device to "contoso"
client.SetObjectProperty(device, ObjectProperty.WindowsDomain, "contoso");
Channel properties can be modified using the SetChannelProperty
method
//Change the UpperErrorLimit of the channel with ID 2 on the sensor with ID 1002 to 100
client.SetChannelProperty(1002, 2, ChannelProperty.UpperErrorLimit, 100);
//Change the LowerErrorLimit of all channels on the sensor with ID 1001
var channels = client.GetChannels(1001);
client.SetChannelProperty(channels, ChannelProperty.LowerErrorLimit, 50);
Notification Trigger properties can similarly be modified using the SetTriggerProperty
method
//Modify the OnNotificationAction of a Notification Trigger
var action = client.GetNotificationAction("Ticket Notification");
client.SetTriggerProperty(trigger, TriggerProperty.OnNotificationAction, action);
Even properties that appear as "read-only" in PRTG can be modified by SetObjectProperty
//Modify the EXE/Script executed by an EXE/XML Advanced sensor
client.SetObjectProperty(1003, ObjectProperty.ExeFile, "newScript.ps1");
When modifying a property with SetObjectProperty
or SetChannelProperty
, PrtgAPI performs a type lookup of the specified property and verifies that the specified value is convertable to the target type. Type information is derived from the corresponding property returned from one of the Get<object>Properties
methods (or in the case of Channels, the type of the property found on the Channel
object).
PrtgAPI understands any dependent properties a property may have, and updates the values of these properties as well to make sure the target property takes effect. For example, as the WindowsDomain
property of an object is not active unless the InheritWindowsCredentials
property is false, PrtgAPI will update the value of this property as well. This extends to multi-level relationships
//Set the database port under the "Credentials for Database Management Systems" section
//to 8080. DBPortMode will also be set to Manual, and InheritDBCredentials will also be
//set to False
client.SetObjectProperty(1001, ObjectProperty.DBPort, 8080);
Multiple properties can be specified at once by specifying a collection of PropertyParameter
, ChannelParameter
or CustomParameter
objects
client.SetObjectProperty(
1001,
new PropertyParameter(ObjectProperty.VMwareUserName, "root"),
new PropertyParameter(ObjectProperty.VMwarePassword, "password")
);
Note: from PRTG 18.1.38 it is no longer possible to enable channel limits or set an error or warning message without having first set a limit value on at least one limit field (UpperErrorLimit
, LowerErrorLimit
, UpperWarningLimit
or LowerWarningLimit
). If PrtgAPI detects you are using version 18.1 or higher it will automatically validate all target channels have an existing limit value when trying to modify the ErrorLimitMessage
, WarningLimitMessage
or set LimitsEnabled
to true. If any channels do not contain a limit value, an InvalidOperationException
will be thrown, specifying the IDs of the sensors whose channel was missing a value.
PRTG allows the unit factor of channels to be controlled via the Channel Unit Configuration section found on the Settings page of devices, groups and probes. Based on the current factor that is defined for a channel, this can influence how values are interpreted when modifying channel properties that relate to the channel's unit (e.g. a channel under a device whose a Bytes (Disk) is set to MByte
should interpret setting an UpperErrorLimit
of 100
differently than a channel under a device whose Bytes (Disk) is set to GByte
).
Both PRTG and PrtgAPI work around this issue by specifying the unit factor of a channel when executing a request. Unit factors can be viewed by inspecting the Factor
property of Channel
objects. While there is absolutely no need for you to utilize this property directly, as a consequence of this behavior it is important to note that
- Modifying the Channel Unit Configuration properties of a PRTG object may invalidate the
Factor
property of any descendantChannel
objects you currently hold reference to - When modifying properties that require specifying a unit factor, PrtgAPI will inspect the
Factor
of all channels to determine how to construct the request.
As a result, requests like the following
// Don't do this
var channel = client.GetChannel(1001, 1);
client.SetChannelProperty(channel.SensorId, channel.Id, ChannelProperty.UpperErrorLimit, 100);
are extremely inefficient, as the Channel
object will need to be retrieved again inside of SetChannelProperty
. Instead, simply pass the channel objects straight to SetChannelProperty
//Do this instead
var channel = client.GetChannel(1001, 1);
client.SetChannelProperty(channel, ChannelProperty.UpperErrorLimit, 100);
When viewing the current values of channels, the DisplayLastValue
property will display a string containing the current value in terms of its custom unit. LastValue
however will always display the value in terms of its raw underlying unit (e.g. bytes).
C:\> Get-Sensor *mem* | Get-Channel *mem* | fl Name,*Last*
Name : Percent Available Memory
DisplayLastValue : 27 %
LastValue : 27
Name : Available Memory
DisplayLastValue : 1,116 MByte
LastValue : 1169711104
Certain properties, such as Scanning Interval, support a range of valid values that can also be customized by the administrator. PrtgAPI defines custom types for representing these values, allowing static values to be accessed via predefined constants, or dynamic values to be used via a cast.
client.SetObjectProperty(1234, ObjectProperty.Interval, ScanningInterval.ThirtySeconds);
client.SetObjectProperty(1234, ObjectProperty.Interval, (ScanningInterval) new TimeSpan(0, 0, 30));
Note: if a custom scanning interval is specified that is not supported by PRTG, PRTG will automatically select the closest interval to the specified value.
For properties not yet supported by PrtgAPI's type system, it is still possible to retrieve such properties via the GetObjectPropertiesRaw
method. As is the case when retrieving supported properties, either an object ID or existing object reference can be specified.
//Retrieve all properties present on the settings page of the probe with ID 3002
var properties = client.GetObjectPropertiesRaw(3002);
Console.WriteLine($"Hello, my name is {properties["name"]}");
GetObjectPropertiesRaw
returns a dictionary containing all properties present on an object. Object properties can be referred to by their raw property names (with trailing underscores removed). GetObjectPropertiesRaw
can also be used for identifying raw property names to potentially use with SetObjectPropertyRaw
(see below). Typically, all raw property names (with the exception of inheritance related properties) returned by GetObjectPropertiesRaw
will require a trailing underscore in order to directly manipulate them.
Note that due to limitations of the PRTG API, it is not possible to properly retrieve all raw properties of objects that you have read-only access to. To retrieve properties of read-only objects you must use the GetObjectPropertyRaw
method (see below).
Individual raw properties can be retrieved via the GetObjectPropertyRaw
method. Properties returned by GetObjectPropertyRaw
will always be returned as strings, leaving it up to the programmer to parse them. PRTG does not support the retrieval of individual inheritance settings; as such, these settings must be retrieved via GetObjectPropertiesRaw
.
var name = client.GetObjectPropertyRaw(1001, "name_");
When retrieving option properties, by default PRTG will return the internal numeric value that is used to represent the value. The label of the selected value (as displayed in the PRTG UI) can alternatively be retrieved by specifying text: true
var rights = client.GetObjectPropertyRaw(1001, "sshelevatedrights", true);
When retrieving individual object properties, please note that if your PRTG server is not in English and you attempt to retrieve an individual property that does not exist on the target object, due to limitations of the PRTG API you may receive the string "(Property does not exist)" in your server's native language.
Properties can be modified using their raw names via the SetObjectPropertyRaw
method.
client.SetObjectPropertyRaw(1001, "name_", "New Name!");
Multiple properties can be modified by specifying an array of CustomParameter
objects
client.SetObjectPropertyRaw(
1001,
new CustomParameter("name_", "New Name!"),
new CustomParameter("interval_", "60|60 seconds")
);
If you prefer to extract raw property details straight from PRTG, this can typically be done by inspecting the "name" and "value" attributes of the properties' <input>
tag in the HTML of the object's Settings page in PRTG.
<input class="text valid" data-rule-required="true" type="text" name="name_"
id="name_" value="dc-1">
When modifying raw properties whose values are populated from dropdown lists, the raw value often has to be in the format <value>|<value>||
client.SetObjectPropertyRaw(1001, "sqlquery_", "test.sql|test.sql||")
Note: unsupported channel properties cannot be modified.
Properties can be retrieved from Sensors, Devices, Groups and Probes using the Get-ObjectProperty
cmdlet
C:\> Get-Sensor -Id 1001 | Get-ObjectProperty
InheritAccess : True
Name : Service: Microsoft Exchange Information Store
ParentTags : {B_Server_Mail}
Tags : {wmiservicesensor, servicesensor}
Priority : Three
InheritChannelUnit :
DebugMode : Discard
...
Based on the type of object requested (sensor, device, group or probe) different properties will be returned. Get-ObjectProperty
is not required for retrieving Channel settings, as these are automatically included in Channel
objects. For more information on retrieving channels, please see Channels.
Certain properties are considered "read-only" when you view them on the Settings page in PRTG. PrtgAPI will endeavor to return these anyway in requests for object properties, and these properties can also be retrieved by asking for them directly.
C:\> Get-Sensor -Id 1001 | Get-ObjectProperty SqlServerQuery
CalculateUptime.sql
When retrieving individual object properties, please note that if your PRTG server is not in English and you attempt to retrieve an individual property that does not exist on the target object, due to limitations of the PRTG API you may receive a deserialization error or the string "(Property does not exist)" in your server's native language.
Note due to the way PrtgAPI retrieves object properties, attempting to retrieve all type safe object properties (by invoking Get-ObjectProperty
with no parameters) will cause a non terminating InvalidOperationException
exception if the current PRTG user has read-only access to the specified object. Singular property parameter sets (GetObjectProperty -Property
) can always be used regardless of whether the current user has read or write access.
Object properties currently supported by PrtgAPI are documented across several PowerShell help articles. For more information, please see the following documents
-
Get-Help SensorSettings
- Sensors -
Get-Help ObjectSettings
- Devices, Groups and Probes -
Get-Help ChannelSettings
- Channels
Properties for Sensors, Devices, Groups and Probes can be modified using the Set-ObjectProperty
cmdlet, while Channel and Notification Trigger properties can be modified using the Set-ChannelProperty
and Set-TriggerProperty
cmdlets respectively. By default, these cmdlets operate in batch mode and are also capable of executing in PassThru Mode. For information on batch mode and PassThru Mode, please see Batch Requests and PassThru Requests respectively.
# Set the default scanning interval of sensors under the device with ID 1001
# to 30 seconds
Get-Device -Id 1001 | Set-ObjectProperty Interval 00:00:30
# Set the upper error limit of the "Total" channel of all WMI CPU Load sensors to 90
Get-Sensor -Tags wmicpu* | Get-Channel Total | Set-ChannelProperty UpperErrorLimit 90
# Set the OnNotificationAction of all triggers on the contoso probe to "Ticket Notification"
Get-Probe contoso | Get-Trigger | Set-TriggerProperty OnNotificationAction *ticket*
Even properties that appear as "read-only" in PRTG can be modified by Set-ObjectProperty
# Modify the EXE/Script executed by an EXE/XML Advanced sensor
Get-Sensor -Tags xmlexesensor -count 1 | Set-ObjectProperty ExeFile newScript.ps1
When modifying a property with Set-ObjectProperty
, PrtgAPI performs a type lookup of the specified property and verifies that the specified value is convertable to the target type. Type information is derived from the corresponding property returned from Get-ObjectProperty
(or in the case of Channels, the type of the property found on the Channel
object returned from Get-Channel
).
PrtgAPI understands any dependent properties a property may have, and updates the values of these properties as well to make sure the target property takes effect. For example, as the Interval
property of an object is not active unless the InheritInterval
property is false, PrtgAPI will update the value of this property as well. This extends to multi-level relationships
# Set the database port under the "Credentials for Database Management Systems" section
# to 8080. "DBPortMode" will also be set to "Manual", and "InheritDBCredentials" will
# also be set to $false
Get-Device -Id 1001 | Set-ObjectProperty DBPort 8080
Multiple properties can be specified at once by specifying the target properties as parameter names
# Create a new device and specify its credentials
Get-Probe | Add-Device esxi-1 | Set-ObjectProperty -VMwareUserName root -VMwarePassword password
PrtgAPI will automatically attempt to coerce the specified value to the property's target type. If the specified value cannot be parsed, PrtgAPI will throw an exception alerting you of the specified and expected type.
When using Set-ChannelProperty
on channels containing scaling custom units (e.g. bytes, megabytes, gigabytes, etc) PrtgAPI will automatically ensure the request is executed in terms of the correct unit for the channel. Depending on your application however it is possible you could get tripped up by this. For more information please see Channel Units.
When entering decimal numbers with Set-ChannelProperty
it is important the number format matches that of the PRTG Server (determined by your PRTG server language); i.e. if PRTG uses commas to represent decimal places, you too must use commas to represent decimal places. If the correct number format is not used, PRTG will likely truncate the specified value, leading to undesirable results. As PowerShell treats commas as arrays, it is important to indicate to PowerShell your value is not an array, such as by representing it as a string.
# Set the UpperErrorLimit to 1.1 on a PRTG server whose number format
# uses commas as the decimal point
$channel | Set-ChannelProperty -UpperErrorLimit "1,1"
If the number format of your operating system does not match the number format of your PRTG server (i.e. a German copy of Windows connecting to an English PRTG server) decimal values will not be serialized correctly. You can bypass this (for both regular objects and channels) by specifying a string containing the decimal value to a PrtgAPI interface that accepts values of type object
# Set the UpperErrorLimit to "1,1" - literally
$channel | Set-ChannelProperty UpperErrorLimit "1,1"
# Depending on your computer's number format, set the UpperErrorLimit to either "11" or "1.1"
# due to PowerShell converting the string to a double before PrtgAPI has a chance to analyze it.
$channel | Set-ChannelProperty -UpperErrorLimit "1,1"
In the first example above, the values UpperErrorLimit
and "1,1"
are specified to the positional -Property <ChannelProperty>
and -Value <object>
parameters respectively, allowing PrtgAPI to perform an intelligent analysis and potentially bypass your system's number parsing settings as per the rules outlined above. In the second example the dynamic -UpperErrorLimit <double>
parameter is specified, resulting in the PowerShell engine attempting to convert the value to a double
for you before passing it to PrtgAPI, preventing PrtgAPI from using its "string literal parsing technique" to properly interpret the value.
Note: from PRTG 18.1.38 it is no longer possible to enable channel limits or set an error or warning message without having first set a limit value on at least one limit field (UpperErrorLimit
, LowerErrorLimit
, UpperWarningLimit
or LowerWarningLimit
). If PrtgAPI detects you are using version 18.1 or higher it will automatically validate all target channels have an existing limit value when trying to modify the ErrorLimitMessage
, WarningLimitMessage
or set LimitsEnabled
to true. If any channels do not contain a limit value, an InvalidOperationException
will be thrown, specifying the IDs of the sensors whose channel was missing a value.
Properties not yet supported by PrtgAPI can still be interacted with via the Raw Parameter Sets of the Get-ObjectProperty
and Set-ObjectProperty
cmdlets.
# Retrieve all properties present on the settings page of the probe with ID 2002
Get-Probe -Id 2002 | Get-ObjectProperty -Raw
Get-ObjectProperty -Raw
returns a PSObject
containing all raw properties present on an object (with trailing underscores removed from all property names). Properties that are not included in the output from GetObjectProperty -Raw
can be directly requested by specifying one or more -RawProperty
values. If a single -RawProperty
is requested, PrtgAPI will simply return the string response from PRTG. If multiple properties are specified however, PrtgAPI will wrap the values of these properties in a PSObject
for easier access.
C:\> Get-Sensor *sql* | Get-ObjectProperty -RawProperty name_,sqlquery_
name : Microsoft SQL
sqlquery : test.sql
PRTG does not support the retrieval of individual inheritance properties; as such, these properties must be retrieved via Get-ObjectProperty
/ Get-ObjectProperty -Raw
(for supported and unsupported properties, respectively)
Note that due to limitations of the PRTG API, it is not possible to properly retrieve all raw properties of objects that you have read-only access to. To retrieve properties of read-only objects you must use Get-ObjectProperty
with the -RawProperty
parameter (see below).
When retrieving option properties, by default PRTG will return the internal numeric value that is used to represent the value. The label of the selected value (as displayed in the PRTG UI) can alternatively be retrieved by specifying -Text
C:\> Get-Probe -Count 1 | Get-ObjectProperty -RawProperty sshelevatedrights -Text
Run the command as the user connecting (default)
When retrieving individual object properties, please note that if your PRTG server is not in English and you attempt to retrieve an individual property that does not exist on the target object, due to limitations of the PRTG API you may receive the string "(Property does not exist)" in your server's native language.
Property values can be modified via their raw names by passing the -RawProperty
and -RawValue
parameters to Set-ObjectProperty
Get-Sensor ping | Set-ObjectProperty -RawProperty name_ -RawValue "Ping"
By default, Set-ObjectProperty
will warn you when attempting to modify raw properties to ensure you understand that this is a risky operation. This prompt can be bypassed by specifying the -Force
parameter
Get-Sensor ping | Set-ObjectProperty -RawProperty name_ -RawValue "Ping" -Force
Multiple raw properties can be modified at once by specifying a hashtable
Get-Sensor ping | Set-ObjectProperty -RawParameters @{
"scheduledependency" = 0
"schedule_" = Get-PrtgSchedule "Weekdays Nine-To-Five*"
}
If you prefer to extract raw property details straight from PRTG, this can typically be done by inspecting the "name" and "value" attributes of the properties' <input>
tag in the HTML of the object's Settings page in PRTG.
<input class="text valid" data-rule-required="true" type="text" name="name_"
id="name_" value="dc-1">
When modifying raw properties whose values are populated from dropdown lists, the raw value often has to be in the format <value>|<value>||
Get-Sensor -Tags sqlsensor | Set-ObjectProperty -RawProperty sqlquery_ -RawValue "test.sql|test.sql||"
Care should be taken when interacting with raw properties (especially properties involving radio buttons), as specifying invalid values can cause minor corruption to PRTG (such as no item being selected). Any corruption that may occur can be easily rectified in the PRTG UI.
Note: unsupported channel properties cannot be modified.