feat(scheduled-jobs): the Task Scheduler as scheduled jobs (#8) #9

Merged
christianmanivong merged 2 commits from feature/scheduled-jobs into main 2026-11-03 08:20:27 +00:00
Owner

Summary

The Task Scheduler as napalm-device-types' ScheduledJobsMixin: every task of a Windows host is read as a scheduled job, any task can be enabled, disabled or started, and an application can create, change and delete its own tasks. It works over PowerShell Remoting, one script per call, like every other getter.

Changes

  • get_scheduled_jobs: one script (Get-ScheduledTask + Get-ScheduledTaskInfo), projected onto flat fields. Key task:<path><name>, kind="task", triggers summarised (weekly on Sun at 01:00, daily at 00:00, every 1 hour for 1 day). A task under \Microsoft\ is platform, any other admin, and a root task whose description starts with napalm-scheduled-job: <its name> is application. Times come back as ISO 8601 UTC (ISO, /Date(ms)/ or epoch accepted), the never-run date 1999-11-30 becomes None, LastTaskResult 0 becomes success, running becomes running, and any other code is hex. The time zone is mapped from the Windows id to IANA with a table of the common zones, else None. A reading that is cut short, or holds fewer tasks than it counted, raises.
  • manage_scheduled_job: Enable- / Disable- / Start-ScheduledTask. The task is matched by exact path and name, never by -TaskName, which takes wildcards. run says the task was started, not that it finished. A disabled task, or one that does not allow a start on demand, is not offered run.
  • put_scheduled_job: Register-ScheduledTask -Xml -Force in the root folder \ under spec["name"], so create and change write the whole definition the same way. The command runs as cmd.exe /d /s /c "<command>" and must be one line. The principal is SYSTEM or a local user via S4U, with no stored password. The description is napalm-scheduled-job: <name> <description> plus a line schedule: <cron>, so the reading gives back the cron expression and command. The digest also covers the triggers.
  • Cron to triggers (task_xml.py): a shape Task Scheduler can express exactly becomes triggers. That covers every day, weekdays, or days of the month in some months; times as one trigger each, evenly spaced times as one repetition, or one repeating trigger per hour; at most 48 triggers. @reboot becomes a boot trigger. These shapes are refused with ScheduledJobRefused, naming why: cron's either-day rule, a weekday combined with days or months, and more than 48 triggers.
  • delete_scheduled_job: Unregister-ScheduledTask -Confirm:$false, for application tasks only.
  • Every write reads again and checks the digest first, and refuses to overwrite a task of the same name (case-insensitive) that an application did not write. Every value is single-quoted with its quotes doubled.
  • _as_list / _ps_quote moved to _powershell.py and are shared. napalm-device-types>=4.26.0. CHANGELOG and README updated, and tools/harvest.py records the new script.

Related Issue

Closes #8
Part of NetOrk/netork#1933

Testing

  • pytest: 202 passed, coverage 98% (floor 95). The new tests run against a synthetic JSON fixture: platform, admin and application tasks, a never-run task, /Date()/ dates, COM handler, group principal, event triggers, the single-object quirk at every level, cut-short and miscounted readings. They also cover the quote doubling, every cron shape taken and refused, and the round trip from written XML back to the spec.
  • ruff format, ruff check, mypy, napalm-standard check and ratchet, and bandit are clean.
  • Not run against a Windows host: the fixture is the shape the script is designed to emit, and the XML has not been registered on a real host yet.
## Summary The Task Scheduler as napalm-device-types' `ScheduledJobsMixin`: every task of a Windows host is read as a scheduled job, any task can be enabled, disabled or started, and an application can create, change and delete its own tasks. It works over PowerShell Remoting, one script per call, like every other getter. ## Changes - `get_scheduled_jobs`: one script (`Get-ScheduledTask` + `Get-ScheduledTaskInfo`), projected onto flat fields. Key `task:<path><name>`, `kind="task"`, triggers summarised (`weekly on Sun at 01:00`, `daily at 00:00, every 1 hour for 1 day`). A task under `\Microsoft\` is `platform`, any other `admin`, and a root task whose description starts with `napalm-scheduled-job: <its name>` is `application`. Times come back as ISO 8601 UTC (ISO, `/Date(ms)/` or epoch accepted), the never-run date 1999-11-30 becomes `None`, `LastTaskResult` 0 becomes `success`, running becomes `running`, and any other code is hex. The time zone is mapped from the Windows id to IANA with a table of the common zones, else `None`. A reading that is cut short, or holds fewer tasks than it counted, raises. - `manage_scheduled_job`: `Enable-` / `Disable-` / `Start-ScheduledTask`. The task is matched by exact path and name, never by `-TaskName`, which takes wildcards. `run` says the task was started, not that it finished. A disabled task, or one that does not allow a start on demand, is not offered `run`. - `put_scheduled_job`: `Register-ScheduledTask -Xml -Force` in the root folder `\` under `spec["name"]`, so create and change write the whole definition the same way. The command runs as `cmd.exe /d /s /c "<command>"` and must be one line. The principal is `SYSTEM` or a local user via S4U, with no stored password. The description is `napalm-scheduled-job: <name> <description>` plus a line `schedule: <cron>`, so the reading gives back the cron expression and command. The digest also covers the triggers. - Cron to triggers (`task_xml.py`): a shape Task Scheduler can express exactly becomes triggers. That covers every day, weekdays, or days of the month in some months; times as one trigger each, evenly spaced times as one repetition, or one repeating trigger per hour; at most 48 triggers. `@reboot` becomes a boot trigger. These shapes are refused with `ScheduledJobRefused`, naming why: cron's either-day rule, a weekday combined with days or months, and more than 48 triggers. - `delete_scheduled_job`: `Unregister-ScheduledTask -Confirm:$false`, for application tasks only. - Every write reads again and checks the digest first, and refuses to overwrite a task of the same name (case-insensitive) that an application did not write. Every value is single-quoted with its quotes doubled. - `_as_list` / `_ps_quote` moved to `_powershell.py` and are shared. `napalm-device-types>=4.26.0`. CHANGELOG and README updated, and `tools/harvest.py` records the new script. ## Related Issue Closes #8 Part of NetOrk/netork#1933 ## Testing - `pytest`: 202 passed, coverage 98% (floor 95). The new tests run against a synthetic JSON fixture: platform, admin and application tasks, a never-run task, `/Date()/` dates, COM handler, group principal, event triggers, the single-object quirk at every level, cut-short and miscounted readings. They also cover the quote doubling, every cron shape taken and refused, and the round trip from written XML back to the spec. - `ruff format`, `ruff check`, `mypy`, `napalm-standard check` and `ratchet`, and `bandit` are clean. - Not run against a Windows host: the fixture is the shape the script is designed to emit, and the XML has not been registered on a real host yet.
christianmanivong added 1 commit 2026-11-03 04:49:35 +00:00
feat(scheduled-jobs): the Task Scheduler as scheduled jobs (#8)
driver / standard (pull_request) Successful in 14s
driver / lint (pull_request) Successful in 15s
driver / test (3.12) (pull_request) Failing after 14s
driver / types (pull_request) Failing after 23s
driver / test (3.13) (pull_request) Failing after 13s
driver / lowest (pull_request) Failing after 14s
driver / security (pull_request) Failing after 32s
driver / build (pull_request) Successful in 25s
CI / driver (pull_request) Failing after 1m21s
driver / publish (pull_request) Skipped
a508b872b0
netOrk shows and controls every scheduled job of a host; on Windows that
is the Task Scheduler. The driver now implements napalm-device-types'
ScheduledJobsMixin over PowerShell Remoting, one script per call as every
getter does.

get_scheduled_jobs reads every task with its run info in one script
(Get-ScheduledTask, Get-ScheduledTaskInfo) as task:<path><name>, its
triggers summarised. Tasks under \Microsoft\ are the platform's, others
the admin's: Windows does not record which software installed a task.
The time zone is mapped to IANA for the common Windows zones, else None.
A reading cut short, or holding fewer tasks than it counted, raises.

manage_scheduled_job switches the task's own flag or starts it;
Start-ScheduledTask returns once the task has started, so the result says
that and no more. A disabled task, or one that refuses a start on demand,
is not offered run.

put_scheduled_job registers an application's task \<name> in the root
folder from XML, so a create and a change write the whole definition the
same way: the command runs in cmd.exe /d /s /c, the principal is SYSTEM
or a local user without a stored password (S4U), and the cron expression
becomes triggers only where Task Scheduler can say it exactly; any other
shape is refused, naming why. The description keeps the job's name and
cron expression, so the reading gives back what was written, and the
digest also covers the triggers, so a change by hand is seen.
delete_scheduled_job unregisters such a task and no other. Every write
reads the task again first, and every value goes into PowerShell
single-quoted with its quotes doubled.

Requires napalm-device-types 4.26.0.

Closes #8
christianmanivong added 1 commit 2026-11-03 07:36:01 +00:00
chore(scheduled-jobs): require napalm-device-types 4.27.0
driver / standard (pull_request) Successful in 14s
driver / lint (pull_request) Successful in 12s
driver / types (pull_request) Successful in 54s
driver / test (3.12) (pull_request) Successful in 55s
driver / test (3.13) (pull_request) Successful in 46s
driver / lowest (pull_request) Successful in 32s
driver / build (pull_request) Successful in 27s
driver / security (pull_request) Successful in 1m1s
CI / driver (pull_request) Successful in 2m22s
driver / publish (pull_request) Skipped
74a8c53c7c
4.26.0 went out with the sshd drop-in change; the scheduled-jobs
contract is in 4.27.0.
christianmanivong merged commit 37708009a0 into main 2026-11-03 08:20:27 +00:00
Sign in to join this conversation.
No Reviewers
1 Participants
Notifications
Due Date
No due date set.
Blocks
You do not have permission to read 1 dependency
Reference: NAPALM/napalm-windows#9