Scheduled Jobs

A scheduled job runs an action on a schedule you define — once, on a repeating interval, or on a cron expression. Jobs can push a deployment, run a command, collect inventory, scan for Windows updates, or run a server-side maintenance task such as a database backup. Manage jobs from the console, the REST API, or the PowerShell module.

How scheduling works#

Every scheduled job combines a schedule type (when it runs) with an action type (what it does). The server owns the timing, so jobs keep running on schedule independently of any console session — there is nothing to install on a workstation. Agent tasks (deployments, commands, inventory, update scans) run against the agents you target; server tasks (backups, cleanups, collection refresh, settings sync) and module tasks (such as BitLocker enforcement and key rotation) run on the Athena server itself and need no targets.

Managing scheduled jobs requires the Operator or Admin role; deleting a job requires Admin. See Roles & Permissions.

Schedule types#

A OneTime job moves to the Completed status after it runs. A Recurring or Cron job keeps running until you pause or delete it.

Cron expressions#

Athena accepts the standard 5-field cron format (minute hour day-of-month month day-of-week). You can also supply a native 6- or 7-field expression if you need second-level precision. Some common patterns:

You can validate an expression before saving and get a human-readable description of it with GET api/scheduler/validate-cron?expression=…. The server returns whether the expression is valid, a plain-English description, and an error message when it is not.

Action types#

Agent tasks act on endpoints and require at least one target — supplied as agent IDs (targetAgentIds) and/or tags (targetTags):

Server tasks run on the Athena server and take no targets. They are intended for routine maintenance:

In the console's Schedule Task picker, the core server tasks appear under Server Tasks (marked Admin Only) and are shown only to users with the Admin role.

Module tasks#

Some modules add their own server tasks to the Scheduler. They appear in the task picker in a separate Module Tasks group, and they run, report and keep history exactly like core server tasks — no targets, and no per-task parameters. The module tasks currently shipped are:

Module tasks carry their own permission, checked twice:

• When you create the job — you need scheduler.manage and the task's own permission. The picker lists only the module tasks you hold the permission for; an unknown task ID is rejected with 400, and a task whose permission you lack is rejected with 403 ("You do not hold the permission this module action requires.").
• Every time the job runs — the user who created the job must still exist, be active, and still hold the permission. If that access has been revoked, the run is not performed and is recorded as failed with the message "The job's creator '…' no longer holds the '…' permission this action requires." Re-create the job under an account that holds the permission.

If the module that provides a task is no longer available on the server, each run is recorded as failed ("Module action '…' is not available on this server."). A task that errors is always recorded as a failed run with the error message — it never stops the Scheduler or other jobs.

Job status & lifecycle#

A scheduled job is always in one of four states, and the actions you can take depend on it:

Pause applies only to an Active job; resume applies only to a Paused job; update and trigger now apply to Active or Paused jobs. Triggering a job runs it immediately without affecting its regular schedule. Each job tracks its next and last run time, run counts, and the last result so you can see at a glance whether it is healthy.

Creating a job via the API#

Post a job definition to POST api/scheduler/jobs. A cron-based deployment that runs daily at midnight against a tag:

POST /api/scheduler/jobs
{
  "name": "Nightly app rollout",
  "description": "Push the line-of-business app every night",
  "scheduleType": "Cron",
  "actionType": "Deployment",
  "cronExpression": "0 0 * * *",
  "deploymentId": "550e8400-e29b-41d4-a716-446655440000",
  "targetTags": ["workstations"]
}

A one-time command at a fixed maintenance window:

POST /api/scheduler/jobs
{
  "name": "Patch-window restart",
  "scheduleType": "OneTime",
  "actionType": "Command",
  "scheduledTime": "2026-01-15T02:00:00",
  "command": "shutdown /r /t 60",
  "targetTags": ["windows-servers"]
}

A server task — a weekly database backup — needs no targets:

POST /api/scheduler/jobs
{
  "name": "Weekly DB backup",
  "scheduleType": "Cron",
  "actionType": "DatabaseBackup",
  "cronExpression": "0 3 * * 0"
}

A module task uses actionType ModuleAction with the task ID in command — here, BitLocker key rotation every day at 02:30:

POST /api/scheduler/jobs
{
  "name": "Daily BitLocker key rotation",
  "scheduleType": "Cron",
  "actionType": "ModuleAction",
  "command": "bitlocker.rotate",
  "cronExpression": "30 2 * * *"
}

GET api/scheduler/module-actions lists the module tasks you may schedule (tasks whose permission you lack are omitted). Each entry has the task ID (actionType — pass it as command) and the permission it requires.

Scheduler endpoints#

All scheduler endpoints require authentication; see the API Reference.

PowerShell#

The Athena PowerShell module manages scheduled jobs end to end:

# Create a recurring inventory collection every hour for two agents
New-AthenaScheduledJob -Name "Hourly inventory" -ScheduleType Recurring `
    -ActionType InventoryCollection -IntervalMinutes 60 `
    -TargetAgentIds @($agent1Id, $agent2Id)

# Create a daily deployment via cron, targeting a tag
New-AthenaScheduledJob -Name "Daily rollout" -ScheduleType Cron `
    -ActionType Deployment -CronExpression "0 0 * * *" `
    -DeploymentId $deploymentId -TargetTags @("workstations")

# Create a weekly server-side database backup (no targets needed)
New-AthenaScheduledJob -Name "Weekly DB backup" -ScheduleType Cron `
    -ActionType DatabaseBackup -CronExpression "0 3 * * 0"

# Push settings to sync peers every night at 01:00
New-AthenaScheduledJob -Name "Nightly settings sync" -ScheduleType Cron `
    -ActionType SettingsSync -CronExpression "0 1 * * *"

# Module task: BitLocker enforcement every 60 minutes (task ID goes in -Command)
New-AthenaScheduledJob -Name "BitLocker enforcement" -ScheduleType Recurring `
    -ActionType ModuleAction -Command "bitlocker.evaluate" -IntervalMinutes 60

Listing, filtering, and managing existing jobs:

# List jobs, with optional filters
Get-AthenaScheduledJob
Get-AthenaScheduledJob -Status Active
Get-AthenaScheduledJob -ActionType Deployment
Get-AthenaScheduledJob -Search "backup"

# Update, pause, resume, run now, and view history
Set-AthenaScheduledJob -Id $jobId -CronExpression "0 2 * * *"
Suspend-AthenaScheduledJob -Id $jobId   # pause
Resume-AthenaScheduledJob -Id $jobId
Start-AthenaScheduledJob -Id $jobId    # trigger now
Get-AthenaScheduledJobHistory -Id $jobId -Count 20

# Dashboard counts, and remove a job (Admin)
Get-AthenaSchedulerStats
Remove-AthenaScheduledJob -Id $jobId