Schedules - lordmilko/PrtgAPI GitHub Wiki
Schedules supported by PRTG can be retrieved via the GetSchedules method
var schedules = client.GetSchedules();When retrieving Schedules, one or more SearchFilter objects can be specified to limit the returned results. Note however that not all Property values supported by PRTG are compatible with notification action queries. As such, if you find your specified filter does not work, you may want to filter within your application instead of within PRTG.
//Get the schedule with ID 630
var schedule = client.GetSchedules(Property.Id, 301).FirstOrDefault();When retrieving a particular notification action you insist should exist, it is possible to use the singular GetSchedule method, returning a single Schedule rather than a List<Schedule> as with GetSchedules.
GetSchedule supports filtering by either the object name or object ID
var schedule = client.GetSchedule(300);var schedule = client.GetSchedule("Weekdays [GMT+0800]");If exactly one schedule with the specified ID or name is not returned, GetSchedule will throw an InvalidOperationException. If you are not sure whether exactly one schedule with the specified ID or name exists, you should use GetSchedules instead and check for the presence of any results.
var schedule = client.GetSchedules(Property.Id, 630).SingleOrDefault();
if (schedule != null)
Console.WriteLine($"Found exactly one schedule: '{schedule}'!");When synchronously retrieving Schedule objects via the GetSchedules method, PrtgAPI will automatically populate all enhanced object properties (including the details of each notification type - i.e. Email, SMS, Ticket, etc). When retrieving schedules via any other method (for example GetNotificationTriggers or GetNotificationActions) PrtgAPI will defer loading these properties (and invoking a web request) until these properties are actually accessed.
Schedule objects retrieved via asynchronous requests (including GetSchedulesAsync / GetNotificationActionsAsync / GetNotificationTriggersAsync) are always loaded immediately so that any secondary requests can be executed in parallel for multiple objects.
The weekly timetable of a Schedule can be accessed via the TimeTable property
var schedule = client.GetSchedules().First();
Console.WriteLine($"Schedule {schedule} is active at these times: {schedule.TimeTable}");The schedule TimeTable provides a variety of different views which can be used to interrogate the times the schedule is active:
- Indexers: retrieves the
TimeSlotobject(s) for a specified hour and/or day of the week -
Rows: provides a custom view representing the days the timetable is active for a specified hour of the day. Provides a high simplified overview of the schedule. -
Grid: provides access to the underlying cells of theTimeTable, storing the 24 hours of each day for each day of the week. Allows iteration over all levels of the timetable
// Indexers
var tuesday = timetable[DayOfWeek.Tuesday];
var wednesday1am = timetable[1, DayOfWeek.Wednesday];
var oneAM = timetable[1];//Rows
foreach (var row in timetable.Rows)
{
if (row.Tuesday)
Console.WriteLine($"{row.Time} is active Tuesday");
else
{
var days = row.ToString().Replace($"{row.Time} ", "");
Console.WriteLine($"{row.Time} is not active Tuesday, but is active {days}");
}
}//Grid
foreach (var day in timetable.Grid)
{
foreach (var slot in day.Value)
{
Console.WriteLine($"{slot.Hour} ({slot.Day}): {slot.Active}");
}
}Schedules supported by PRTG can be retrieved via the Get-PrtgSchedule cmdlet
C:\> Get-PrtgSchedule
Name Id TimeTable
---- -- ---------
Weekdays [GMT+0800] 620 {00:00 Weekdays, 01:00 Weekdays, 02:00...
Weekends [GMT+0800] 621 {00:00 Weekends, 01:00 Weekends, 02:00...
Sundays [GMT+0800] 622 {00:00 Sunday, 01:00 Sunday, 02:00 Sun...
...Schedules can be filtered to those with a specific -Name
C:\> Get-PrtgSchedule week*
Name Id TimeTable
---- -- ---------
Weekdays [GMT+0800] 620 {00:00 Weekdays, 01:00 Weekdays, 02:00...
Weekends [GMT+0800] 621 {00:00 Weekends, 01:00 Weekends, 02:00...or -Id
C:\> Get-PrtgSchedule -Id 620
Name Id TimeTable
---- -- ---------
Weekdays [GMT+0800] 620 {00:00 Weekdays, 01:00 Weekdays, 02:00...While Get-PrtgSchedule also supports the use of advanced Filters, note however that not all Property values supported by PRTG are compatible with schedule queries. As such, if you find your specified filter does not work, you may want to filter within your script instead of within PRTG.
When retrieving Schedule objects via the Get-PrtgSchedule cmdlet, PrtgAPI will automatically populate all enhanced object properties (including the TimeTable, Active status, etc). When retrieving actions via any other cmdlet (for example Get-NotificationTrigger or Get-NotificationAction) PrtgAPI will defer loading these properties (and invoking a web request) until these properties are actually accessed.
While modifying the the Schedule of objects with PrtgAPI is technically possible, note that any properties in the Schedules, Dependencies and Maintenance Window section of PRTG not specified in your API requests will automatically become unset.
By inspecting the TimeTable property of a schedule, it is possible to get a graphical display of the days it is active
C:\> (Get-PrtgSchedule -Id 620).TimeTable
Time Monday Tuesday Wednesday Thursday Friday Saturday Sunday
---- ------ ------- --------- -------- ------ -------- ------
00:00 True True True True True False False
01:00 True True True True True False False
02:00 True True True True True False False
03:00 True True True True True False False
04:00 True True True True True False False
05:00 True True True True True False False
06:00 True True True True True False False
07:00 True True True True True False False
...TimeTable objects automatically convert themselves to an IEnumerable<TimeSlotRow> for display in PowerShell. It is still possible to interact with the TimeTable object however via its usual Rows, Grid and indexer members
C:\> $timetable = (Get-PrtgClient -Id 620).TimeTable
C:\> $timetable[[DayOfWeek]::Sunday]
Hour Day Active
---- --- ------
0 Sunday True
1 Sunday True
2 Sunday True
3 Sunday True
...C:\> $timetable[1, [DayOfWeek]::Sunday]
Hour Day Active
---- --- ------
1 Sunday TruePrtgAPI does not currently provide any native facilities for modifying the properties of Schedules (including TimeTables), however this can still be achieved via the Set-ObjectProperty cmdlet
# Enable monitoring across all hours of the week
Get-PrtgSchedule -Id 620 | Set-ObjectProperty -RawParameters @{
timetable = 0..167
timetable_ = ""
}Simply set the hours you would like to activate on the timetable property. 0 indicates 12:00am Monday, while 167 indicates 11:00pm Sunday. Any values that were previously set on the schedule that are not specified in this request will become unset
The following prototype demonstrates a way you might possibly achieve this
function HoursToInts([DateTime[]]$hours)
{
foreach($hour in $hours)
{
$diff = [int][DayOfWeek]::Monday - [int]$hour.DayOfWeek
$mondayMidnight = $hour.AddDays($diff).Date
$timeSpan = $hour - $mondayMidnight
if($timeSpan.TotalHours -lt 0)
{
return 168 + [int]$timeSpan.TotalHours
}
return [int]$timeSpan.TotalHours
}
}
function MakeDate([DayOfWeek]$day, $hour)
{
$date = (New-Object DateTime).AddDays(7)
$diff = [int]$day - [int]$date.DayOfWeek
$date = $date.AddDays($diff).AddHours($hour)
HoursToInts $date
}
# Construct an arbitrary date from a day of the week and an hour. You could alternatively
# simply specify an array of DateTime objects to HourToInt; as long as we get a DateTime
# with the right day and hour, it doesn't really matter how you make it
$date1 = MakeDate Sunday 13
$date2 = MakeDate Monday 2
$indexes = $date1,$date2
# Modify the timetable
Get-PrtgSchedule -Id 620 | Set-ObjectProperty -RawParameters @{
timetable = $indexes
timetable_ = ""
} -Force
# Now check the results!
(Get-PrtgSchedule -Id 620).TimeTableTime Monday Tuesday Wednesday Thursday Friday Saturday Sunday
---- ------ ------- --------- -------- ------ -------- ------
...
02:00 True False False False False False False
...
13:00 False False False False False False True
...