Building a scheduled task with the ScheduledTasks module: action, trigger, principal, and result codes

Goal

Register a scheduled task from PowerShell with an explicit action, trigger and run-as principal, and confirm afterward whether it actually ran successfully.

Prerequisites

Administrator rights to register a task that runs as SYSTEM or another account; the built-in ScheduledTasks module.

Steps

1. Define what runs: $action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-NoProfile -File C:\Scripts\cleanup.ps1".
2. Define when: $trigger = New-ScheduledTaskTrigger -Daily -At 3am.
3. Define who it runs as. To avoid storing and rotating a password, run under a well-known system account: $principal = New-ScheduledTaskPrincipal -UserId "NT AUTHORITY\SYSTEM" -LogonType ServiceAccount -RunLevel Highest. The Register-ScheduledTask documentation notes that a password "is ignored for the well-known system accounts," which it lists as NT AUTHORITY\SYSTEM, NT AUTHORITY\LOCALSERVICE, and NT AUTHORITY\NETWORKSERVICE; -RunLevel accepts Limited or Highest. For a task that needs network credentials or a specific identity instead, use a domain account with -LogonType Password (and pass -User/-Password to Register-ScheduledTask), or a group Managed Service Account (DOMAIN\svc-task$) with -LogonType Password and no password at all — Windows retrieves the gMSA password from Active Directory.
4. Register: Register-ScheduledTask -TaskName "NightlyCleanup" -Action $action -Trigger $trigger -Principal $principal.
5. Confirm registration: Get-ScheduledTask -TaskName "NightlyCleanup".
6. After a run, read the last result rather than assuming success: Get-ScheduledTaskInfo -TaskName "NightlyCleanup" | Select-Object LastRunTime, LastTaskResult. Get-ScheduledTaskInfo "gets the last run-time information for a scheduled task." A result of 0 means success; Task Scheduler's own documented constants include SCHED_S_TASK_RUNNING (0x00041301), a status value meaning the task instance is still running, not an error — treat any non-zero, non-"still running" code as a failure to investigate.

Expected result

Get-ScheduledTask shows the task as Ready; after its scheduled time, Get-ScheduledTaskInfo shows a recent LastRunTime and a LastTaskResult of 0.

Limits and test basis

A task set to run only "when logged on" instead of ServiceAccount/Password logon types will not run unattended — check -LogonType if a scheduled task silently never fires. To undo: Unregister-ScheduledTask -TaskName "NightlyCleanup" -Confirm:$false removes it cleanly for non-interactive use; export it first with Export-ScheduledTask -TaskName "NightlyCleanup" > task-backup.xml if it may need to be re-imported later via Register-ScheduledTask -Xml. No reboot is required; the task is live as soon as it is registered.