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
- cmd (str):
- (required) The command or executable to run.
- arguments (str):
(optional) Arguments to be passed to the command or executable. To launch a script the first command will need to be the interpreter for the script. For example, to run a vbscript you would pass
cscript.exe
in thecmd
parameter and pass the script in thearguments
parameter as follows:
cmd='cscript.exe' arguments='c:\scripts\myscript.vbs'
Batch files do not need an interpreter and may be passed to the cmd parameter directly.
- start_in (str):
- (optional) The current working directory for the command.
Send and email. Requires
server
,from
, andto
orcc
.from (str): The sender
reply_to (str): Who to reply to
to (str): The recipient
cc (str): The CC recipient
bcc (str): The BCC recipient
subject (str): The subject of the email
body (str): The Message Body of the email
server (str): The server used to send the email
- attachments (list):
- A list of attachments. These will be the paths to the files to attach. ie:
attachments="['C:\attachment1.txt', 'C:\attachment2.txt']"
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.
- title (str):
- The dialog box title.
- message (str):
- The dialog box message body
Returns: | A dictionary containing the task configuration |
---|---|
Return type: | dict |
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, delay=None, **kwargs)¶Add a trigger to a Windows Scheduled task
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.
Parameters: |
|
---|
kwargs
There are optional keyword arguments determined by the type of trigger being defined. They are as follows:
Event
The trigger will be fired by an event.
- 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
The task will run daily.
- 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
The task will run weekly.
- 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.
- days_of_week (list):
- Sets the days of the week on which the task runs. Should be a list. ie:
['Monday','Wednesday','Friday']
. Valid entries are the names of the days of the week.
Monthly
The task will run monthly.
- months_of_year (list):
- Sets the months of the year during which the task runs. Should be a list. ie:
['January','July']
. Valid entries are the full names of all the months.- days_of_month (list):
- Sets the days of the month during which the task runs. Should be a list. ie:
[1, 15, 'Last']
. Options are all days of the month 1 - 31 and the word 'Last' to indicate the last day of the month.- last_day_of_month (bool):
Boolean value that indicates that the task runs on the last day of the month regardless of the actual date of that day.
Note
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
The task will run monthly an the specified day.
- months_of_year (list):
- Sets the months of the year during which the task runs. Should be a list. ie:
['January','July']
. Valid entries are the full names of all the months.- weeks_of_month (list):
Sets the weeks of the month during which the task runs. Should be a list. ie:
['First','Third']
. Valid options are:
- First
- Second
- Third
- Fourth
- last_week_of_month (bool):
- Boolean value that indicates that the task runs on the last week of the month.
- days_of_week (list):
- Sets the days of the week during which the task runs. Should be a list. ie:
['Monday','Wednesday','Friday']
. Valid entries are the names of the days of the week.
OnIdle
No special parameters required.
OnTaskCreation
No special parameters required.
OnBoot
No special parameters required.
OnLogon
No special parameters required.
OnSessionChange
The task will be triggered by a session change.
- session_user_name (str):
- Sets the user for the Terminal Server session. When a session state change is detected for this user, a task is started. To detect session status change for any user, do not pass this parameter.
- state_change (str):
Sets the kind of Terminal Server session change that would trigger a task launch. Valid options are:
- ConsoleConnect: When you connect to a user session (switch users)
- ConsoleDisconnect: When you disconnect a user session (switch users)
- RemoteConnect: When a user connects via Remote Desktop
- RemoteDisconnect: When a user disconnects via Remote Desktop
- SessionLock: When the workstation is locked
- SessionUnlock: When the workstation is unlocked
Returns: | True if successful, otherwise False |
---|---|
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: |
|
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: |
|
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: |
|
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: |
|
Return type: |
CLI Example:
salt '*' 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: |
|
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: |
|
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: |
|
---|---|
Returns: |
|
Return type: |
CLI Example:
salt '*' 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: | A dictionary containing the task configuration |
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:
# List all actions for a task in the default location
salt 'minion-id' task.list_actions <task_name>
# List all actions for the XblGameSaveTask in the Microsoft\XblGameSave
# location
salt 'minion-id' task.list_actions XblGameSaveTask Microsoft\XblGameSave
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:\Windows\System32\tasks ). |
---|---|
Returns: | Returns a list of folders. |
Return type: | list |
CLI Example:
# List all folders in the default location
salt 'minion-id' task.list_folders
# List all folders in the Microsoft directory
salt 'minion-id' task.list_folders Microsoft
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:\Windows\System32\tasks ). |
---|---|
Returns: | Returns a list of tasks |
Return type: | list |
CLI Example:
# List all tasks in the default location
salt 'minion-id' task.list_tasks
# List all tasks in the Microsoft\XblGameSave Directory
salt 'minion-id' task.list_tasks Microsoft\XblGameSave
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:
# List all triggers for a task in the default location
salt 'minion-id' task.list_triggers <task_name>
# List all triggers for the XblGameSaveTask in the Microsoft\XblGameSave
# location
salt '*' task.list_triggers XblGameSaveTask Microsoft\XblGameSave
salt.modules.win_task.
run
(name, location='\\')¶Run a scheduled task manually.
Parameters: | |
---|---|
Returns: |
|
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: |
|
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: |
CLI Example:
salt 'minion-id' task.list_status <task_name>
salt.modules.win_task.
stop
(name, location='\\')¶Stop a scheduled task.
Parameters: | |
---|---|
Returns: |
|
Return type: |
CLI Example:
salt 'minion-id' task.list_stop <task_name>
Docs for previous releases are available on readthedocs.org.
Latest Salt release: 2019.2.1