Windows Task Scheduler Module .. versionadded:: 2016.3.0
A module for working with the Windows Task Scheduler. You can add and edit existing tasks. You can add and clear triggers and actions. You can list all tasks, folders, triggers, and actions.
salt.modules.win_task.
add_action
(name=None, location='\\', action_type='Execute', **kwargs)¶Add an action to a task.
Parameters: |
|
---|
Required arguments for each action_type:
Execute - Execute a command or an executable
Parameters: |
|
---|
Email - Send and email. Requires server
, from
, and to
or
cc
.
Parameters: |
|
---|
Message - Display a dialog box. The task must be set to “Run only when user is logged on” in order for the dialog box to display. Both parameters are required.
Parameters: | |
---|---|
Returns: | True if successful, False if unsuccessful |
Return type: |
CLI Example:
salt 'minion-id' task.add_action <task_name> cmd='del /Q /S C:\\Temp'
salt.modules.win_task.
add_trigger
(name=None, location='\\', trigger_type=None, trigger_enabled=True, start_date=None, start_time=None, end_date=None, end_time=None, random_delay=None, repeat_interval=None, repeat_duration=None, repeat_stop_at_duration_end=False, execution_time_limit=None, **kwargs)¶Parameters: |
|
---|
Parameters: |
---|
Parameters: | start_time (str) – The time when the trigger is activated. If no value is passed, midnight will be used. Can be one of the following formats: |
---|
Parameters: | end_date (str) – The date when the trigger is deactivated. The trigger cannot start the task after it is deactivated. Can be one of the following formats: |
---|
Parameters: | end_time (str) – The time when the trigger is deactivated. If the this
is not passed with end_date it will be set to midnight. Can be one
of the following formats: |
---|
Parameters: | random_delay (str) – The delay time that is randomly added to the start time of the trigger. Valid values are: |
---|
Parameters: | repeat_interval (str) – The amount of time between each restart of the task. Valid values are: |
---|
Parameters: | repeat_duration (str) – How long the pattern is repeated. Valid values are: |
---|
Parameters: |
---|
kwargs
There are optional keyword arguments determined by the type of trigger being defined. They are as follows:
Event
Parameters: | subscription (str) – An event definition in xml format that fires the trigger. The easiest way to get this would is to create an event in windows task scheduler and then copy the xml text. |
---|
Once
No special parameters required.
Daily
Parameters: | days_interval (int) – The interval between days in the schedule. An interval of 1 produces a daily schedule. An interval of 2 produces an every-other day schedule. If no interval is specified, 1 is used. Valid entries are 1 - 999. |
---|
Weekly
Parameters: | weeks_interval (int) – The interval between weeks in the schedule. An interval of 1 produces a weekly schedule. An interval of 2 produces an every-other week schedule. If no interval is specified, 1 is used. Valid entries are 1 - 52. |
---|
Monthly
Parameters: |
|
---|
You can set the task to run on the last day of the month by either including the word ‘Last’ in the list of days, or setting the parameter ‘last_day_of_month` equal to True.
MonthlyDay
Parameters: |
|
---|
Parameters: |
---|
OnIdle No special parameters required.
OnTaskCreation No special parameters required.
OnBoot No special parameters required.
OnLogon No special parameters required.
OnSessionChange
Parameters: |
|
---|
Note
Arguments are parsed by the YAML loader and are subject to yaml’s
idiosyncrasies. Therefore, time values in some formats (%H:%M:%S
and
%H:%M
) should to be quoted. See YAML IDIOSYNCRASIES for more details.
Returns: | True if successful, False if unsuccessful |
---|---|
Return type: | bool |
CLI Example:
salt 'minion-id' task.add_trigger <task_name> trigger_type=Once trigger_enabled=True start_date=2016/12/1 start_time='"12:01"'
salt.modules.win_task.
clear_triggers
(name, location='\\')¶Remove all triggers from the task.
Parameters: | |
---|---|
Returns: | True if successful, False if unsuccessful |
Return type: |
CLI Example:
salt 'minion-id' task.clear_trigger <task_name>
salt.modules.win_task.
create_folder
(name, location='\\')¶Create a folder in which to create tasks.
Parameters: | |
---|---|
Returns: | True if successful, False if unsuccessful |
Return type: |
CLI Example:
salt 'minion-id' task.create_folder <folder_name>
salt.modules.win_task.
create_task
(name, location='\\', user_name='System', password=None, force=False, **kwargs)¶Create a new task in the designated location. This function has many keyword arguments that are not listed here. For additional arguments see:
Parameters: |
|
---|---|
Returns: | True if successful, False if unsuccessful |
Return type: |
CLI Example:
salt 'minion-id' task.create_task <task_name> user_name=System force=True action_type=Execute cmd='del /Q /S C:\\Temp' trigger_type=Once start_date=2016-12-1 start_time=01:00
salt.modules.win_task.
create_task_from_xml
(name, location='\\', xml_text=None, xml_path=None, user_name='System', password=None)¶Create a task based on XML. Source can be a file or a string of XML.
Parameters: |
|
---|---|
Returns: | True if successful, False if unsuccessful |
Return type: |
CLI Example:
salt 'minion-id' task.create_task_from_xml <task_name> xml_path=C:\task.xml
salt.modules.win_task.
delete_folder
(name, location='\\')¶Delete a folder from the task scheduler.
Parameters: | |
---|---|
Returns: | True if successful, False if unsuccessful |
Return type: |
CLI Example:
salt 'minion-id' task.delete_folder <folder_name>
salt.modules.win_task.
delete_task
(name, location='\\')¶Delete a task from the task scheduler.
Parameters: | |
---|---|
Returns: | True if successful, False if unsuccessful |
Return type: |
CLI Example:
salt 'minion-id' task.delete_task <task_name>
salt.modules.win_task.
edit_task
(name=None, location='\\', user_name=None, password=None, description=None, enabled=None, hidden=None, run_if_idle=None, idle_duration=None, idle_wait_timeout=None, idle_stop_on_end=None, idle_restart=None, ac_only=None, stop_if_on_batteries=None, wake_to_run=None, run_if_network=None, network_id=None, network_name=None, allow_demand_start=None, start_when_available=None, restart_every=None, restart_count=3, execution_time_limit=None, force_stop=None, delete_after=None, multiple_instances=None, **kwargs)¶Edit the parameters of a task. Triggers and Actions cannot be edited yet.
Parameters: |
|
---|
Note
The combination of user_name and password determine how the task runs. For example, if a username is passed without at password the task will only run when the user is logged in. If a password is passed as well the task will run whether the user is logged on or not. If you pass ‘System’ as the username the task will run as the system account (the password parameter is ignored.
Parameters: |
|
---|
Parameters: | idle_wait_timeout (str) – A value that indicates the amount of time that the Task Scheduler will wait for an idle condition to occur. Valid values are: |
---|
Parameters: |
|
---|
Parameters: |
|
---|
Parameters: |
|
---|
Parameters: | multiple_instances (str) – Sets the policy that defines how the Task Scheduler deals with multiple instances of the task. Valid values are: |
---|
Returns: | True if successful, False if unsuccessful |
---|---|
Return type: | bool |
CLI Example:
salt 'minion-id' task.edit_task <task_name> description='This task is awesome'
salt.modules.win_task.
info
(name, location='\\')¶Get the details about a task in the task scheduler.
Parameters: | |
---|---|
Returns: | |
Return type: |
CLI Example:
salt 'minion-id' task.info <task_name>
salt.modules.win_task.
list_actions
(name, location='\\')¶List all actions that pertain to a task in the specified location.
Parameters: | |
---|---|
Returns: | Returns a list of actions. |
Return type: |
CLI Example:
salt 'minion-id' task.list_actions <task_name>
salt.modules.win_task.
list_folders
(location='\\')¶List all folders located in a specific location in the task scheduler.
Parameters: | location (str) – A string value representing the folder from which you want to list tasks. Default is ‘' which is the root for the task scheduler (C:WindowsSystem32tasks). |
---|---|
Returns: | Returns a list of folders. |
Return type: | list |
CLI Example:
salt 'minion-id' task.list_folders
salt.modules.win_task.
list_tasks
(location='\\')¶List all tasks located in a specific location in the task scheduler.
Parameters: | location (str) – A string value representing the folder from which you want to list tasks. Default is ‘' which is the root for the task scheduler (C:WindowsSystem32tasks). |
---|---|
Returns: | Returns a list of tasks. |
Return type: | list |
CLI Example:
salt 'minion-id' task.list_tasks
salt.modules.win_task.
list_triggers
(name, location='\\')¶List all triggers that pertain to a task in the specified location.
Parameters: | |
---|---|
Returns: | Returns a list of triggers. |
Return type: |
CLI Example:
salt 'minion-id' task.list_triggers <task_name>
salt.modules.win_task.
run
(name, location='\\')¶Run a scheduled task manually.
Parameters: | |
---|---|
Returns: | True if successful, False if unsuccessful |
Return type: |
CLI Example:
salt 'minion-id' task.list_run <task_name>
salt.modules.win_task.
run_wait
(name, location='\\')¶Run a scheduled task and return when the task finishes
Parameters: | |
---|---|
Returns: | True if successful, False if unsuccessful |
Return type: |
CLI Example:
salt 'minion-id' task.list_run_wait <task_name>
salt.modules.win_task.
status
(name, location='\\')¶Determine the status of a task. Is it Running, Queued, Ready, etc.
Parameters: | |
---|---|
Returns: | The current status of the task. Will be one of the following: |
Return type: | string |
---|
CLI Example:
salt 'minion-id' task.list_status <task_name>
salt.modules.win_task.
stop
(name, location='\\')¶Stop a scheduled task.
Parameters: | |
---|---|
Returns: | True if successful, False if unsuccessful |
Return type: |
CLI Example:
salt 'minion-id' task.list_stop <task_name>
Docs for previous releases are available on readthedocs.org.
Latest Salt release: 2018.3.3