TaskScheduler

This page is still a work in progress.

The TaskScheduler UDF offers functions to control and manipulate the Windows Task Scheduler.

Structure

The UDF uses the Windows Task Scheduler Object Model

Details can be found here:

Object/Collection	Object/Collection	Object/Collection	Object/Collection	Object/Collection	Object/Collection	Object/Collection
Action	Actions	IdleSettings	NetworkSettings	Principal	RegisteredTask	RegisteredTasks
RegistrationInfo	RepetitionPattern	RunningTask	RunningTasks	Settings	TaskDefinition	Folder
Folders	NamedValues	NamedValuePair	TaskService	Trigger	Triggers

How to create a task

There's more than one way to skin a cat - I mean: to create a task. This list is sorted from easy to hard:

1. Use the Task Scheduler GUI and create the task ;-)
2. Use the wrapper functions provided by the UDF
3. Use a template task and export it to a file. Modify the created XML source file and import it using the Task Scheduler GUI
4. Export the XML source of an existing task using _TS_TaskExportXML to memory or to a file, modify this XML source and create a new task using _TS_TaskImportXML
5. Retrieve the properties of an existing task to memory, modify the properties and create the new task by using _TS_TaskCreate, _TS_TaskPropertiesSet and _TS_TaskRegister
6. Retrieve the properties of an existing task as AutoIt array code, copy the array from the console to your script, modify the properties and create a new task using _TS_TaskCreate, _TS_TaskPropertiesSet and _TS_TaskRegister

Use the Task Scheduler GUI

The web is full of videos and tutorials describing how to create tasks using the Task Scheduler GUI (example).

Using Wrapper functions

Call the wrapper functions in the following sequence:

• _TS_Wrapper_TaskCreate: Create the TaskDefinition object and set a few general properties
• _TS_Wrapper_PrincipalSet: Set the principal properties of a task like logon type, run level
• _TS_Wrapper_TriggerLogon: Set a trigger to start a task when a user logs on. More trigger functions are available
• _TS_Wrapper_ActionCreate: Set the action to be executetd whent a task gets started
• _TS_Wrapper_TaskRegister: Register the task in a folder and pass some additional properties

Example (for better readability all error checking has been removed):

#include <TaskScheduler.au3>

; Prepare start and end date of the trigger. Format must be YYYY-MM-DDTHH:MM:SS
Global $sStartDateTime = _DateAdd("n", 2, _NowCalc()) ; Start two minutes from now
$sStartDateTime = StringReplace($sStartDateTime, "/", "-")
$sStartDateTime = StringReplace($sStartDateTime, " ", "T")
Global $sEndDateTime = _DateAdd("M", 4, _NowCalc()) ; End 4 months from now
$sEndDateTime = StringReplace($sEndDateTime, "/", "-")
$sEndDateTime = StringReplace($sEndDateTime, " ", "T")

; Connect to the Task Scheduler Service
Global $oService = _TS_Open()

; Create task "Test_Logon" in folder "\Test" to run Notepad 2 minutes after the user logged on
Global $oTaskDefinition = _TS_Wrapper_TaskCreate($oService, "Test-Description", "Test-Doku" & @CRLF & "Line 2")
_TS_Wrapper_PrincipalSet($oTaskDefinition, $TASK_LOGON_INTERACTIVE_TOKEN)
_TS_Wrapper_TriggerLogon($oTaskDefinition, 2, $sStartDateTime, $sEndDateTime)
_TS_Wrapper_ActionCreate($oTaskDefinition, "CMD")
_TS_Wrapper_TaskRegister($oService, "Test", "Test-Logon", $oTaskDefinition, Default, Default, $TASK_LOGON_INTERACTIVE_TOKEN)

Export/Modify/Import XML

The web is full of videos and tutorials describing how to export and import a task as XML using the Task Scheduler GUI (example).

Create task using _TS_TaskExportXML/_TS_TaskImportXML

Please have a look at the _TS_TaskCopy function in the UDF. This function shows how to create a new task using both XML inport/export functions.

Example (for better readability all error checking has been removed):

Global $oService = _TS_Open()
; Import task "\test\Test-Task" as XML to an array
Local $aSourceTaskXML = _TS_TaskExportXML($oService, "\Test\Test-Task")
; Modify $aSourceTaskXML as desired here
; Create the new task in the same folder with name "Test-Task-NEW" from the modified array
Global $oTask = _TS_TaskImportXML($oService, "\Test\Test-Task-NEW", 2, $aSourceTaskXML)

Functions

_TS_Open

Connects to the Task Scheduler Service and additionally allows to control and manipulate the Task Scheduler on another computer.

You must ensure the following before you begin (more details can be found here):

• Your computer and the remote computer must be part of a domain or a Workgroup
• You must know the IP Address of the remote computer
• You must have the login credentials for the remote computer and the login credential must be part of the Administrators group on the remote computer
• You may want to ensure that your Firewall allows “Remote Scheduled Tasks Management”

Examples how to connect to another computer (thanks to AdamUL for testing):

; Connect to a computer in AD where the current user is in a the local Admininstrators group 
; on that computer, via domain or local group, or directly. Use AD computer name.
Global $oService = _TS_Open("COMPUTERNAME")

; Connect to a computer in AD where the entered user (AdminUser) is an AD user, and is in the 
; local Administrators group on that computer, via domain or local group, or directly. Use AD computer name.
Global $oService = _TS_Open("COMPUTERNAME", "AdminUser", "AD", "Password") 

; Connect to a computer in AD where the entered local user (Administrator) is NOT an AD user, 
; and is in the local Administrators group on that computer, via local group, or directly. Use AD computer name.
Global $oService = _TS_Open("COMPUTERNAME", "Administrator", ".", "Password") 

; Non-domain computer where the entered local user (Administrator) is in the local Administrators group 
; on that computer. Use IP address or DNS name to connect.
Global $oService = _TS_Open("192.168.0.1", "Administrator", ".", "Password")

Debugging connection problems

At the bottom of this github page you will find a tool named "Task Scheduler Configuration Troubleshooter". It analyzes possible connection problems and tells you what to do or even tries to solve the problem.