salt.modules.win_task¶

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:

• name (str) -- The name of the task to which to add the action.

• location (str) -- A string value representing the location of the task. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

• action_type (str) --

  The type of action to add. There are three action types. Each one requires its own set of Keyword Arguments (kwargs). Valid values are:

  • Execute

  • Email

  • Message

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 the cmd parameter and pass the script in the arguments 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.

Email

Send and email. Requires server, from, and to or cc.

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:

• name (str) -- The name of the task to which to add the trigger.

• location (str) -- A string value representing the location of the task. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

• trigger_type (str) --

  The type of trigger to create. This is defined when the trigger is created and cannot be changed later. Options are as follows:

  • Event

  • Once

  • Daily

  • Weekly

  • Monthly

  • MonthlyDay

  • OnIdle

  • OnTaskCreation

  • OnBoot

  • OnLogon

  • OnSessionChange

• trigger_enabled (bool) -- Boolean value that indicates whether the trigger is enabled.

• start_date (str) --

  The date when the trigger is activated. If no value is passed, the current date will be used. Can be one of the following formats:

  • %Y-%m-%d

  • %m-%d-%y

  • %m-%d-%Y

  • %m/%d/%y

  • %m/%d/%Y

  • %Y/%m/%d

• 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:

  • %I:%M:%S %p

  • %I:%M %p

  • %H:%M:%S

  • %H:%M

• 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:

  • %Y-%m-%d

  • %m-%d-%y

  • %m-%d-%Y

  • %m/%d/%y

  • %m/%d/%Y

  • %Y/%m/%d

• end_time (str) --

  The time when the trigger is deactivated. If this is not passed with end_date it will be set to midnight. Can be one of the following formats:

  • %I:%M:%S %p

  • %I:%M %p

  • %H:%M:%S

  • %H:%M

• random_delay (str) --

  The delay time that is randomly added to the start time of the trigger. Valid values are:

  • 30 seconds

  • 1 minute

  • 30 minutes

  • 1 hour

  • 8 hours

  • 1 day

  Note

  This parameter applies to the following trigger types

  • Once

  • Daily

  • Weekly

  • Monthly

  • MonthlyDay

• repeat_interval (str) --

  The amount of time between each restart of the task. Valid values are:

  • 5 minutes

  • 10 minutes

  • 15 minutes

  • 30 minutes

  • 1 hour

• repeat_duration (str) --

  How long the pattern is repeated. Valid values are:

  • Indefinitely

  • 15 minutes

  • 30 minutes

  • 1 hour

  • 12 hours

  • 1 day

• repeat_stop_at_duration_end (bool) -- Boolean value that indicates if a running instance of the task is stopped at the end of the repetition pattern duration.

• execution_time_limit (str) --

  The maximum amount of time that the task launched by the trigger is allowed to run. Valid values are:

  • 30 minutes

  • 1 hour

  • 2 hours

  • 4 hours

  • 8 hours

  • 12 hours

  • 1 day

  • 3 days (default)

• delay (str) --

  The time the trigger waits after its activation to start the task. Valid values are:

  • 15 seconds

  • 30 seconds

  • 1 minute

  • 30 minutes

  • 1 hour

  • 8 hours

  • 1 day

  Note

  This parameter applies to the following trigger types:

  • OnLogon

  • OnBoot

  • Event

  • OnTaskCreation

  • OnSessionChange

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 on 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:

• name (str) -- The name of the task from which to clear all triggers.

• location (str) -- A string value representing the location of the task. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

Returns:

True if successful, otherwise False

Return type:

bool

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:

• name (str) -- The name of the folder. This will be displayed in the task scheduler.

• location (str) -- A string value representing the location in which to create the folder. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

Returns:

True if successful, otherwise False

Return type:

bool

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:

• edit_task()

• add_action()

• add_trigger()

Parameters:

• name (str) -- The name of the task. This will be displayed in the task scheduler.

• location (str) -- A string value representing the location in which to create the task. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

• user_name (str) -- The user account under which to run the task. To specify the 'System' account, use 'System'. The password will be ignored.

• password (str) -- The password to use for authentication. This should set the task to run whether the user is logged in or not, but is currently not working.

• force (bool) -- If the task exists, overwrite the existing task.

Returns:

True if successful, otherwise False

Return type:

bool

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:

• name (str) -- The name of the task. This will be displayed in the task scheduler.

• location (str) -- A string value representing the location in which to create the task. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

• xml_text (str) -- A string of xml representing the task to be created. This will be overridden by xml_path if passed.

• xml_path (str) -- The path to an XML file on the local system containing the xml that defines the task. This will override xml_text

• user_name (str) -- The user account under which to run the task. To specify the 'System' account, use 'System'. The password will be ignored.

• password (str) -- The password to use for authentication. This should set the task to run whether the user is logged in or not, but is currently not working.

Returns:

True if successful, otherwise False str: A string with the error message if there is an error

Return type:

bool

Raises:

• ArgumentValueError -- If arguments are invalid

• CommandExecutionError --

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:

• name (str) -- The name of the folder to delete.

• location (str) -- A string value representing the location of the folder. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

Returns:

True if successful, otherwise False

Return type:

bool

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:

• name (str) -- The name of the task to delete.

• location (str) -- A string value representing the location of the task. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

Returns:

True if successful, otherwise False

Return type:

bool

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:

• name (str) -- The name of the task. This will be displayed in the task scheduler.

• location (str) -- A string value representing the location in which to create the task. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

• user_name (str) -- The user account under which to run the task. To specify the 'System' account, use 'System'. The password will be ignored.

• password (str) --

  The password to use for authentication. This should set the task to run whether the user is logged in or not, but is currently not working.

  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).

• description (str) -- A string representing the text that will be displayed in the description field in the task scheduler.

• enabled (bool) -- A boolean value representing whether or not the task is enabled.

• hidden (bool) -- A boolean value representing whether or not the task is hidden.

• run_if_idle (bool) -- Boolean value that indicates that the Task Scheduler will run the task only if the computer is in an idle state.

• idle_duration (str) --

  A value that indicates the amount of time that the computer must be in an idle state before the task is run. Valid values are:

  • 1 minute

  • 5 minutes

  • 10 minutes

  • 15 minutes

  • 30 minutes

  • 1 hour

• 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:

  • Do not wait

  • 1 minute

  • 5 minutes

  • 10 minutes

  • 15 minutes

  • 30 minutes

  • 1 hour

  • 2 hours

• idle_stop_on_end (bool) -- Boolean value that indicates that the Task Scheduler will terminate the task if the idle condition ends before the task is completed.

• idle_restart (bool) -- Boolean value that indicates whether the task is restarted when the computer cycles into an idle condition more than once.

• ac_only (bool) -- Boolean value that indicates that the Task Scheduler will launch the task only while on AC power.

• stop_if_on_batteries (bool) -- Boolean value that indicates that the task will be stopped if the computer begins to run on battery power.

• wake_to_run (bool) -- Boolean value that indicates that the Task Scheduler will wake the computer when it is time to run the task.

• run_if_network (bool) -- Boolean value that indicates that the Task Scheduler will run the task only when a network is available.

• network_id (guid) -- GUID value that identifies a network profile.

• network_name (str) -- Sets the name of a network profile. The name is used for display purposes.

• allow_demand_start (bool) -- Boolean value that indicates that the task can be started by using either the Run command or the Context menu.

• start_when_available (bool) -- Boolean value that indicates that the Task Scheduler can start the task at any time after its scheduled time has passed.

• restart_every (str) --

  A value that specifies the interval between task restart attempts. Valid values are:

  • False (to disable)

  • 1 minute

  • 5 minutes

  • 10 minutes

  • 15 minutes

  • 30 minutes

  • 1 hour

  • 2 hours

• restart_count (int) -- The number of times the Task Scheduler will attempt to restart the task. Valid values are integers 1 - 999.

• execution_time_limit (bool, str) --

  The amount of time allowed to complete the task. Valid values are:

  • False (to disable)

  • 1 hour

  • 2 hours

  • 4 hours

  • 8 hours

  • 12 hours

  • 1 day

  • 3 days

• force_stop (bool) -- Boolean value that indicates that the task may be terminated by using TerminateProcess.

• delete_after (bool, str) --

  The amount of time that the Task Scheduler will wait before deleting the task after it expires. Requires a trigger with an expiration date. Valid values are:

  • False (to disable)

  • Immediately

  • 30 days

  • 90 days

  • 180 days

  • 365 days

• multiple_instances (str) --

  Sets the policy that defines how the Task Scheduler deals with multiple instances of the task. Valid values are:

  • Parallel

  • Queue

  • No New Instance

  • Stop Existing

Returns:

True if successful, otherwise False

Return type:

bool

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:

• name (str) -- The name of the task for which to return the status

• location (str) -- A string value representing the location of the task. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

Returns:

A dictionary containing the task configuration

Return type:

dict

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:

• name (str) -- The name of the task for which list actions.

• location (str) -- A string value representing the location of the task from which to list actions. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

Returns:

Returns a list of actions.

Return type:

list

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:

• name (str) -- The name of the task for which list triggers.

• location (str) -- A string value representing the location of the task from which to list triggers. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

Returns:

Returns a list of triggers.

Return type:

list

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:

• name (str) -- The name of the task to run.

• location (str) -- A string value representing the location of the task. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

Returns:

True if successful, otherwise False

Return type:

bool

CLI Example:

salt 'minion-id' task.run <task_name>

salt.modules.win_task.run_wait(name, location='\\')¶

Run a scheduled task and return when the task finishes

Parameters:

• name (str) -- The name of the task to run.

• location (str) -- A string value representing the location of the task. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

Returns:

True if successful, otherwise False

Return type:

bool

CLI Example:

salt 'minion-id' task.run_wait <task_name>

salt.modules.win_task.status(name, location='\\')¶

Determine the status of a task. Is it Running, Queued, Ready, etc.

Parameters:

• name (str) -- The name of the task for which to return the status

• location (str) -- A string value representing the location of the task. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

Returns:

The current status of the task. Will be one of the following:

• Unknown

• Disabled

• Queued

• Ready

• Running

Return type:

str

CLI Example:

salt 'minion-id' task.list_status <task_name>

salt.modules.win_task.stop(name, location='\\')¶

Stop a scheduled task.

Parameters:

• name (str) -- The name of the task to stop.

• location (str) -- A string value representing the location of the task. Default is \ which is the root for the task scheduler (C:\Windows\System32\tasks).

Returns:

True if successful, otherwise False

Return type:

bool

CLI Example:

salt 'minion-id' task.list_stop <task_name>