win_scheduled_task - Manage scheduled tasks

New in version 2.0.

Synopsis

  • Creates/modified or removes Windows scheduled tasks.

Parameters

Parameter Choices/Defaults Comments
actions
(added in 2.5)
A list of action to configure for the task.
See suboptions for details on how to construct each list entry.
When creating a task there MUST be at least one action but when deleting a task this can be a null or an empty list.
The ordering of this list is important, the module will ensure the order is kept when modifying the task.
This module only supports the ExecAction type but can still delete the older legacy types.
path
required
The path to the executable for the ExecAction.
working_directory
The working directory to run the executable from.
arguments
An argument string to supply for the executable.
allow_demand_start
(added in 2.5)
    Choices:
  • no
  • yes
Whether the task can be started by using either the Run command or the Context menu.
allow_hard_terminate
(added in 2.5)
    Choices:
  • no
  • yes
Whether the task can be terminated by using TerminateProcess.
arguments
Arguments to provide for a scheduled task action.
DEPRECATED since 2.5, use the actions option instead to specify a list of actions to run.
Will be removed in 2.7.

aliases: argument
author
(added in 2.5)
The author of the task.
compatibility
(added in 2.5)
    Choices:
  • 0
  • 1
  • 2
The integer value with indicates which version of Task Scheduler a task is compatible with.
0 means the task is compatible with the AT command.
1 means the task is compatible with Task Scheduler 1.0.
2 means the task is compatible with Task Scheduler 2.0.
date
(added in 2.5)
The date when the task was registered.
days_of_week
Days of the week to run a weekly task.
Specify a list or comma separate days in the full version, e.g. monday instead of mon.
DEPRECATED since 2.5, use the triggers option list with the type of monthlydow or weekly.
Will be removed in 2.7.
delete_expired_task_after
(added in 2.5)
The amount of time that the Task Scheduler will wait before deleting the task after it expires.
A task expires after the end_boundary has been exceeded for all triggers associated with the task.
This is in the ISO 8601 Duration format P[n]Y[n]M[n]DT[n]H[n]M[n]S.
description
(added in 2.5)
The description of the task.
disallow_start_if_on_batteries
(added in 2.5)
    Choices:
  • no
  • yes
Whether the task will not be started if the computer is running on battery power.
display_name
(added in 2.5)
The name of the user/group that is displayed in the Task Scheduler UI.
enabled
(added in 2.5)
    Choices:
  • no
  • yes
Whether the task is enabled, the task can only run when yes.
executable
The path to the executable to run for a scheduled task action.
DEPRECATED since 2.5, use the actions option instead to specify a list of actions to run.
Will be removed in 2.7.
execution_time_limit
(added in 2.5)
The amount of time allowed to complete the task.
When not set, the time limit is infinite.
This is in the ISO 8601 Duration format P[n]Y[n]M[n]DT[n]H[n]M[n]S.
frequency
    Choices:
  • daily
  • once
  • weekly
The frequency of the task to run.
DEPRECATED since 2.5, use the triggers option list and specify the type based on the frequency required.
Will be removed in 2.7.
group
(added in 2.5)
The group that will run the task.
group and username are exclusive to each other and cannot be set at the same time.
logon_type can either be not set or equal group.
hidden
(added in 2.5)
    Choices:
  • no
  • yes
Whether the task will be hidden in the UI.
logon_type
(added in 2.5)
    Choices:
  • none
  • password
  • s4u
  • interactive_token
  • group
  • service_account
  • token_or_password
The logon method that the task will run with.
password means the password will be stored and the task has access to network resources.
s4u means the existing token will be used to run the task and no password will be stored with the task. Means no network or encrypted files access.
interactive_token means the user must already be logged on interactively and will run in an existing interactive session.
group means that the task will run as a group.
service_account means that a service account like System, Local Service or Network Service will run the task.
multiple_instances
(added in 2.5)
    Choices:
  • 0
  • 1
  • 2
  • 3
An integer that indicates the behaviour when starting a task that is already running.
0 will start a new instance in parallel with existing instances of that task.
1 will wait until other instances of that task to finish running before starting itself.
2 will not start a new instance if another is running.
3 will stop other instances of the task and start the new one.
name
required
The name of the scheduled task without the path.
password
(added in 2.4)
The password for the user account to run the scheduled task as.
This is required when running a task without the user being logged in, excluding the builtin service accounts.
If set, will always result in a change unless update_password is set to no and no othr changes are required for the service.
path Default:
\
Task folder in which this task will be stored.
Will create the folder when state=present and the folder does not already exist.
Will remove the folder when state=absent and there are no tasks left in the folder.
priority
(added in 2.5)
The priority level (0-10) of the task.
When creating a new task the default if 7.
restart_count
(added in 2.5)
The number of times that the Task Scheduler will attempt to restart the task.
restart_interval
(added in 2.5)
How long the Task Scheduler will attempt to restart the task.
If this is set then restart_count must also be set.
The maximum allowed time is 31 days.
The minimum allowed time is 1 minute.
This is in the ISO 8601 Duration format P[n]Y[n]M[n]DT[n]H[n]M[n]S.
run_level
(added in 2.4)
    Choices:
  • limited
  • highest
The level of user rights used to run the task.
If not specified the task will be created with limited rights.

aliases: runlevel
run_only_if_idle
(added in 2.5)
    Choices:
  • no
  • yes
Whether the task will run the task only if the computer is in an idle state.
run_only_if_network_available
(added in 2.5)
    Choices:
  • no
  • yes
Whether the task will run only when a network is available.
source
(added in 2.5)
The source of the task.
start_when_available
(added in 2.5)
    Choices:
  • no
  • yes
Whether the task can start at any time after its scheduled time has passed.
state
    Choices:
  • absent
  • present ←
When state=present will ensure the task exists.
When state=absent will ensure the task does not exist.
stop_if_going_on_batteries
(added in 2.5)
    Choices:
  • no
  • yes
Whether the task will be stopped if the computer begins to run on battery power.
store_password
(added in 2.4)
    Choices:
  • no
  • yes ←
Whether to store the password for the user running the task.
If no, the task will only have access to local resources.
DEPRECATED since 2.5, use logon_type=password to set whether to store the password for the task.
Will be removed in 2.7.
time
The start time to execute the scheduled task.
DEPRECATED since 2.5, use the triggers option list and use the start_boundary option to set the start time.
Will be removed in 2.7.
triggers
(added in 2.5)
A list of triggers to configure for the task.
See suboptions for details on how to construct each list entry.
The ordering of this list is important, the module will ensure the order is kept when modifying the task.
There are multiple types of triggers, see https://msdn.microsoft.com/en-us/library/windows/desktop/aa383868.aspx for a list of trigger types and their options.
The suboption options listed below are not required for all trigger types, read the description for more details.
execution_time_limit
The maximum amount of time that the task is allowed to run for.
Optional for all the trigger types.
Is in the ISO 8601 Duration format P[n]Y[n]M[n]DT[n]H[n]M[n]S.
start_boundary
The start time for the task, even if the trigger meets the other start criteria, it won't start until this time is met.
If you wish to run a task at 9am on a day you still need to specify the date on which the trigger is activated, you can set any date even ones in the past.
Required when type is daily, monthlydow, monthly, time, weekly, (session_state_change).
Optional for the rest of the trigger types.
This is in ISO 8601 DateTime format YYYY-MM-DDThh:mm:ss.
enabled
    Choices:
  • no
  • yes
Whether to set the trigger to enabled or disabled
Used in all trigger types.
weeks_interval
The interval of weeks to run on, e.g. 1 means every week while 2 means every other week.
Optional when type=weekly.
run_on_last_week_of_month
    Choices:
  • no
  • yes
Boolean value that sets whether the task runs on the last week of the month.
Optional when type is monthlydow.
subscription
Only used and is required for type=event.
The XML query string that identifies the event that fires the trigger.
end_boundary
The end time for when the trigger is deactivated.
This is in ISO 8601 DateTime format YYYY-MM-DDThh:mm:ss.
days_of_week
The days of the week for the trigger.
Can be a list or comma separated string of full day names e.g. monday instead of mon.
Required when type is weekly, type=session_state_change.
Optional when type=monthlydow.
repetition
Allows you to define the repetition action of the trigger that defines how often the task is run and how long the repetition pattern is repeated after the task is started.
It takes in the following keys, duration, interval, stop_at_duration_end
duration is how long the pattern is repeated and is written in the ISO 8601 Duration format P[n]Y[n]M[n]DT[n]H[n]M[n]S.
interval is the amount of time between earch restart of the task and is written in the ISO 8601 Duration format P[n]Y[n]M[n]DT[n]H[n]M[n]S.
stop_at_duration_end is a boolean value that indicates if a running instance of the task is stopped at the end of the repetition pattern.
user_id
The username that the trigger will target.
Optional when type is logon, session_state_change.
Can be the username or SID of a user.
When type=logon and you want the trigger to fire when a user in a group logs on, leave this as null and set group to the group you wish to trigger.
weeks_of_month
The weeks of the month for the trigger.
Can be a list or comma separated string of the numbers 1 to 4 representing the first to 4th week of the month.
Optional when type=monthlydow.
delay
The time to delay the task from running once the trigger has been fired.
Optional when type is boot, event, logon, registration, session_state_change.
Is in the ISO 8601 Duration format P[n]Y[n]M[n]DT[n]H[n]M[n]S.
random_delay
The delay time that is randomly added to the start time of the trigger.
Optional when type is daily, monthlydow, monthly, time, weekly.
Is in the ISO 8601 Duration format P[n]Y[n]M[n]DT[n]H[n]M[n]S.
run_on_last_day_of_month
    Choices:
  • no
  • yes
Boolean value that sets whether the task runs on the last day of the month.
Optional when type is monthly.
months_of_year
The months of the year for the trigger.
Can be a list or comma separated string of full month names e.g. march instead of mar.
Optional when type is monthlydow, monthly.
type
required
    Choices:
  • boot
  • daily
  • event
  • idle
  • logon
  • monthlydow
  • monthly
  • registration
  • time
  • weekly
  • session_state_change
The trigger type, this value controls what below options are required.
days_of_month
The days of the month from 1 to 31 for the triggers.
If you wish to set the trigger for the last day of any month use run_on_last_day_of_month.
Can be a list or comma separated string of day numbers.
Required when type=monthly.
update_password
(added in 2.5)
    Choices:
  • no
  • yes ←
Whether to update the password even when not other changes have occured.
When yes will always result in a change when executing the module.
username
The user to run the scheduled task as.
Will default to the current user under an interactive token if not specified during creation.

aliases: user
version
(added in 2.5)
The version number of the task.
wake_to_run
(added in 2.5)
    Choices:
  • no
  • yes
Whether the task will wake the computer when it is time to run the task.

Notes

Note

  • In Ansible 2.4 and earlier, this could only be run on Server 2012/Windows 8 or newer. Since 2.5 this restriction has been lifted.
  • The option names and structure for actions and triggers of a service follow the RegisteredTask naming standard and requirements, it would be useful to read up on this guide if coming across any issues https://msdn.microsoft.com/en-us/library/windows/desktop/aa382542.aspx.

Examples

- name: create a task to open 2 command prompts as SYSTEM
  win_scheduled_task:
    name: TaskName
    description: open command prompt
    actions:
    - path: cmd.exe
      arguments: /c hostname
    - path: cmd.exe
      arguments: /c whoami
    triggers:
    - type: daily
      start_boundary: '2017-10-09T09:00:00'
    username: SYSTEM
    state: present
    enabled: yes

- name: create task to run a PS script as NETWORK service on boot
  win_scheduled_task:
    name: TaskName2
    description: Run a PowerShell script
    actions:
    - path: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
      arguments: -ExecutionPolicy Unrestricted -NonInteractive -File C:\TestDir\Test.ps1
    triggers:
    - type: boot
    username: NETWORK SERVICE
    run_level: highest
    state: present

- name: change above task to run under a domain user account, storing the passwords
  win_scheduled_task:
    name: TaskName2
    username: DOMAIN\User
    password: Password
    logon_type: password

- name: change the above task again, choosing not to store the password
  win_scheduled_task:
    name: TaskName2
    username: DOMAIN\User
    logon_type: s4u

- name: create task with multiple triggers
  win_scheduled_task:
    name: TriggerTask
    path: \Custom
    actions:
    - path: cmd.exe
    triggers:
    - type: daily
    - type: monthlydow
    username: SYSTEM

- name: set logon type to password but don't force update the password
  win_scheduled_task:
    name: TriggerTask
    path: \Custom
    actions:
    - path: cmd.exe
    username: Administrator
    password: password
    update_password: no

- name: disable a task that already exists
  win_scheduled_task:
    name: TaskToDisable
    enabled: no

- name: create a task that will be repeated every minute for five minutes
  win_scheduled_task:
    name: RepeatedTask
    description: open command prompt
    actions:
    - path: cmd.exe
      arguments: /c hostname
    triggers:
    - type: registration
      repetition:
      - interval: PT1M
        duration: PT5M
        stop_at_duration_end: yes

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Author

  • Peter Mounce (@petemounce)
  • Jordan Borean (@jborean93)

Hint

If you notice any issues in this documentation you can edit this document to improve it.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.5/modules/win_scheduled_task_module.html