win_scheduled_task – Manage scheduled tasks
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 list 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 | |||
arguments - |
An argument string to supply for the executable. | |||
path - / required |
The path to the executable for the ExecAction. | |||
working_directory - |
The working directory to run the executable from. | |||
allow_demand_start boolean added in 2.5 |
|
Whether the task can be started by using either the Run command or the Context menu. | ||
allow_hard_terminate boolean added in 2.5 |
|
Whether the task can be terminated by using TerminateProcess. | ||
author - added in 2.5 |
The author of the task. | |||
compatibility integer added in 2.5 |
|
The integer value with indicates which version of Task Scheduler a task is compatible with.
| ||
date - added in 2.5 |
The date when the task was registered. | |||
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 | |||
description - added in 2.5 |
The description of the task. | |||
disallow_start_if_on_batteries boolean added in 2.5 |
|
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 boolean added in 2.5 |
|
Whether the task is enabled, the task can only run when | ||
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 | |||
group - added in 2.5 |
The group that will run the task.
| |||
hidden boolean added in 2.5 |
|
Whether the task will be hidden in the UI. | ||
logon_type - added in 2.5 |
|
The logon method that the task will run with.
| ||
multiple_instances integer added in 2.5 |
|
An integer that indicates the behaviour when starting a task that is already running.
| ||
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 | |||
path - |
Default: "\\\\" |
Task folder in which this task will be stored. Will create the folder when Will remove the folder when | ||
priority integer added in 2.5 |
The priority level (0-10) of the task. When creating a new task the default if See https://msdn.microsoft.com/en-us/library/windows/desktop/aa383512.aspx for details on the priority levels. | |||
restart_count integer 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 The maximum allowed time is 31 days. The minimum allowed time is 1 minute. This is in the ISO 8601 Duration format | |||
run_level - added in 2.4 |
|
The level of user rights used to run the task. If not specified the task will be created with limited rights.
| ||
run_only_if_idle boolean added in 2.5 |
|
Whether the task will run the task only if the computer is in an idle state. | ||
run_only_if_network_available boolean added in 2.5 |
|
Whether the task will run only when a network is available. | ||
source - added in 2.5 |
The source of the task. | |||
start_when_available boolean added in 2.5 |
|
Whether the task can start at any time after its scheduled time has passed. | ||
state - |
|
When When | ||
stop_if_going_on_batteries boolean added in 2.5 |
|
Whether the task will be stopped if the computer begins to run on battery power. | ||
triggers list 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. | |||
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 Can be a list or comma separated string of day numbers. Required when | |||
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 Optional when | |||
delay - |
The time to delay the task from running once the trigger has been fired. Optional when Is in the ISO 8601 Duration format | |||
enabled boolean |
|
Whether to set the trigger to enabled or disabled Used in all trigger types. | ||
end_boundary - |
The end time for when the trigger is deactivated. This is in ISO 8601 DateTime format | |||
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 | |||
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 | |||
random_delay - |
The delay time that is randomly added to the start time of the trigger. Optional when Is in the ISO 8601 Duration format | |||
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 string |
Defines how long the pattern is repeated. The value is in the ISO 8601 Duration format By default this is not set which means it will repeat indefinitely. | |||
interval string |
The amount of time between each restart of the task. The value is written in the ISO 8601 Duration format | |||
stop_at_duration_end boolean |
|
Whether a running instance of the task is stopped at the end of the repetition pattern. | ||
run_on_last_day_of_month boolean |
|
Boolean value that sets whether the task runs on the last day of the month. Optional when | ||
run_on_last_week_of_month boolean |
|
Boolean value that sets whether the task runs on the last week of the month. Optional when | ||
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 Optional for the rest of the trigger types. This is in ISO 8601 DateTime format | |||
subscription - |
Only used and is required for The XML query string that identifies the event that fires the trigger. | |||
type - / required |
|
The trigger type, this value controls what below options are required. | ||
user_id - |
The username that the trigger will target. Optional when Can be the username or SID of a user. When | |||
weeks_interval - |
The interval of weeks to run on, e.g. Optional when | |||
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 | |||
update_password boolean added in 2.5 |
|
Whether to update the password even when not other changes have occured. When | ||
username - |
The user to run the scheduled task as. Will default to the current user under an interactive token if not specified during creation.
| |||
version - added in 2.5 |
The version number of the task. | |||
wake_to_run boolean added in 2.5 |
|
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 not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors
- Peter Mounce (@petemounce)
- Jordan Borean (@jborean93)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.7/modules/win_scheduled_task_module.html