An alert schedule is a named set of time windows (e.g. "Business Hours") that an alert rule can optionally restrict itself to -- a rule with no schedule fires any time it triggers; one with a schedule only fires inside one of its windows. A schedule can have any number of windows.

Having trouble reaching the API, or logging in from another machine? See Network Access & Authentication Security -- by default the Api only answers localhost, and PowerShell needs an extra flag once it does answer elsewhere.

Order of Operations

  1. Authenticate to the API.
  2. Create the schedule.
  3. Add its windows.

The calls

GET    /api/alert-schedules
POST   /api/alert-schedules
PUT    /api/alert-schedules/{alertScheduleId}
DELETE /api/alert-schedules/{alertScheduleId}
POST   /api/alert-schedules/{alertScheduleId}/windows
PUT    /api/alert-schedules/windows/{alertScheduleWindowId}
DELETE /api/alert-schedules/windows/{alertScheduleWindowId}

Permission needed: Credential.View to list, Credential.Manage for everything else.

C# example

var jsonOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web);

// Step 1: Authenticate to the API.
using var handler = new HttpClientHandler { UseDefaultCredentials = true };
using var client = new HttpClient(handler) { BaseAddress = new Uri("http://your-minion-agent-server:5443") };
client.DefaultRequestHeaders.Add("X-App-Name", "MyIntegration");

// Step 2: Create the schedule.
var newSchedule = new CreateAlertScheduleRequest(ScheduleName: "Business Hours");
var response = await client.PostAsJsonAsync("/api/alert-schedules", newSchedule, jsonOptions);
response.EnsureSuccessStatusCode();
var created = await response.Content.ReadFromJsonAsync<CreatedIdResponse>(jsonOptions);

// Step 3: Add a window -- Monday through Friday needs one window per day (a window can't span midnight).
foreach (var day in new[] { "Monday", "Tuesday", "Wednesday", "Thursday", "Friday" })
{
    var window = new CreateAlertScheduleWindowRequest(Day: day, StartTime: TimeSpan.Parse("08:00:00"), EndTime: TimeSpan.Parse("18:00:00"));
    (await client.PostAsJsonAsync($"/api/alert-schedules/{created!.Id}/windows", window, jsonOptions)).EnsureSuccessStatusCode();
}

// List every schedule with its windows.
var schedules = await client.GetFromJsonAsync<AlertScheduleSummary[]>("/api/alert-schedules", jsonOptions);
foreach (var s in schedules!)
{
    Console.WriteLine($"{s.AlertScheduleId}: {s.ScheduleName}, active now = {s.IsActiveNow}");
    foreach (var w in s.Windows)
        Console.WriteLine($"  {w.Day} {w.StartTime}-{w.EndTime}");
}

record CreateAlertScheduleRequest(string ScheduleName);
record CreateAlertScheduleWindowRequest(string Day, TimeSpan StartTime, TimeSpan EndTime);
record CreatedIdResponse(int Id);
record AlertScheduleWindowInfo(int AlertScheduleWindowId, string Day, TimeSpan StartTime, TimeSpan EndTime);
record AlertScheduleSummary(int AlertScheduleId, string ScheduleName, bool IsActive, bool IsActiveNow, AlertScheduleWindowInfo[] Windows);

Not on a domain machine? Swap in the app-account login from Calling the API From Your Own Code.

PowerShell example

# Step 1: Authenticate to the API.
$headers = @{ "X-App-Name" = "MyIntegration" }

# Step 2: Create the schedule. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$newSchedule = @{ ScheduleName = "Business Hours" } | ConvertTo-Json
$created = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/alert-schedules" `
    -Method Post -Body $newSchedule -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

# Step 3: Add a window -- Monday through Friday needs one window per day (a window can't span midnight).
foreach ($day in @("Monday", "Tuesday", "Wednesday", "Thursday", "Friday")) {
    $window = @{ Day = $day; StartTime = "08:00:00"; EndTime = "18:00:00" } | ConvertTo-Json
    Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/alert-schedules/$($created.id)/windows" `
        -Method Post -Body $window -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
}

# List every schedule with its windows.
$schedules = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/alert-schedules" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
$schedules | ForEach-Object {
    "$($_.alertScheduleId): $($_.scheduleName), active now = $($_.isActiveNow)"
    $_.windows | ForEach-Object { "  $($_.day) $($_.startTime)-$($_.endTime)" }
}

What you get back

POST /api/alert-schedules / POST .../windows -- 201 Created: { "id": 4 }

GET /api/alert-schedules -- 200 OK, an array with windows nested:

[ { "alertScheduleId": 4, "scheduleName": "Business Hours", "isActive": true, "isActiveNow": true,
    "windows": [ { "alertScheduleWindowId": 9, "day": "Monday", "startTime": "08:00:00", "endTime": "18:00:00" } ] } ]

isActiveNow is computed live, using the same logic the Worker uses to decide whether to actually fire a scheduled rule right now.

PUT/DELETE (schedule or window) -- 204 No Content -- no body.

Codes this call can return

See API Response Codes for what each one means in general. For these calls:

  • 201 -- created.
  • 200 -- the list.
  • 204 -- updated or deleted.
  • 400 -- (create/update schedule) a schedule with that name already exists; (create/update window) EndTime isn't after StartTime (a window can't span midnight -- enter it as two windows instead), or the day/time combination fails validation.
  • 403 -- you don't have the required permission.
  • 409 -- (delete schedule) it's still attached to one or more alert rules -- detach them first. There's no reassign for schedules the way channels and styles have; remove it from each rule (recreate the rule without a schedule, or with a different one) before deleting.

What gets audited

Every mutation here is recorded under AlertSchedule -- Create Alert Schedule, Alter Alert Schedule, Delete Alert Schedule, Add Alert Schedule Window, Alter Alert Schedule Window, Remove Alert Schedule Window. The list GET isn't audited.

See also: Manage Alert Rules, List Alert Channels.