salt.modules.win_task module¶

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

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

kwargs

Required kwargs for each value:

Execute Execute a command or an executable.

Parameters:	cmd (str) -- (required) The command / executable to run. arguments (str) -- (optional) Arguments to be passed to the command /

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.

Parameters:	start_in (str) -- (optional) The current working directory for the

command.

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

Parameters:	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.

Parameters:	title (str) -- The dialog box title. message (str) -- The dialog box message body
Returns:	True if successful, False if unsuccessful
Return type:	bool

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

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

Parameters:	trigger_enabled (bool) -- Boolean value that indicates whether the

trigger is enabled.

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

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: - %I:%M:%S %p - %I:%M %p - %H:%M:%S - %H:%M

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: - %Y-%m-%d - %m-%d-%y - %m-%d-%Y - %m/%d/%y - %m/%d/%Y - %Y/%m/%d

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: - %I:%M:%S %p - %I:%M %p - %H:%M:%S - %H:%M

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

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

Parameters:	repeat_duration (str) -- How long the pattern is repeated. Valid values

are: - Indefinitely - 15 minutes - 30 minutes - 1 hour - 12 hours - 1 day

Parameters:	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.

Parameters:	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)

kwargs

There are optional keyword arguments determined by the type of trigger being defined. They are as follows:

Event :param str subscription: 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 :param int days_interval: 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 :param int weeks_interval: 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.

param list days_of_week: 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 :param list months_of_year: 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.

Parameters:	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.

Parameters:	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.

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 :param list months_of_year: 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.

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

Parameters:	last_week_of_month (bool) -- Boolean value that indicates that the

task runs on the last week of the month.

Parameters:	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 :param str session_user_name: 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.

Parameters:	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, False if unsuccessful
Return type:	bool

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

Returns:	True if successful, False if unsuccessful
Return type:	bool

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.

Parameters:	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:WindowsSystem32tasks).

Returns:	True if successful, False if unsuccessful
Return type:	bool

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:

• py:function::edit_task
• py:function::add_action
• py:function::add_trigger

Parameters:	name (str) -- The name of the task. This will be displayed in the task

scheduler.

Parameters:	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:WindowsSystem32tasks).

Parameters:	user_name (str) -- The user account under which to run the task. To

specify the 'System' account, use 'System'. The password will be ignored.

Parameters:	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.

Parameters:	force (bool) -- If the task exists, overwrite the existing task.
Returns:	True if successful, False if unsuccessful
Return type:	bool

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.

Parameters:	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:WindowsSystem32tasks).

Parameters:	xml_text (str) -- A string of xml representing the task to be created.

This will be overridden by xml_path if passed.

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

Parameters:	user_name (str) -- The user account under which to run the task. To

specify the 'System' account, use 'System'. The password will be ignored.

Parameters:	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, False if unsuccessful
Return type:	bool

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

Returns:	True if successful, False if unsuccessful
Return type:	bool

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

Returns:	True if successful, False if unsuccessful
Return type:	bool

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.

Parameters:	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:WindowsSystem32tasks).

Parameters:	user_name (str) -- The user account under which to run the task. To

specify the 'System' account, use 'System'. The password will be ignored.

Parameters:	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.

Parameters:	description (str) -- A string representing the text that will be

displayed in the description field in the task scheduler.

Parameters:	enabled (bool) -- A boolean value representing whether or not the task is

enabled.

Parameters:	hidden (bool) -- A boolean value representing whether or not the task is

hidden.

Parameters:	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.

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

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: - Do not wait - 1 minute - 5 minutes - 10 minutes - 15 minutes - 30 minutes - 1 hour - 2 hours

Parameters:	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.

Parameters:	idle_restart (bool) -- Boolean value that indicates whether the task is

restarted when the computer cycles into an idle condition more than once.

Parameters:	ac_only (bool) -- Boolean value that indicates that the Task Scheduler

will launch the task only while on AC power.

Parameters:	stop_if_on_batteries (bool) -- Boolean value that indicates that the task

will be stopped if the computer begins to run on battery power.

Parameters:	wake_to_run (bool) -- Boolean value that indicates that the Task

Scheduler will wake the computer when it is time to run the task.

Parameters:	run_if_network (bool) -- Boolean value that indicates that the Task

Scheduler will run the task only when a network is available.

Parameters:	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.

Parameters:	allow_demand_start (bool) -- Boolean value that indicates that the task

can be started by using either the Run command or the Context menu.

Parameters:	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.

Parameters:	restart_every -- A value that specifies the interval between task

restart attempts. Valid values are: :type: bool str - False (to disable) - 1 minute - 5 minutes - 10 minutes - 15 minutes - 30 minutes - 1 hour - 2 hours

Parameters:	restart_count (int) -- The number of times the Task Scheduler will

attempt to restart the task. Valid values are integers 1 - 999.

Parameters:	execution_time_limit -- The amount of time allowed to complete the

task. Valid values are: :type: bool str - False (to disable) - 1 hour - 2 hours - 4 hours - 8 hours - 12 hours - 1 day - 3 days

Parameters:	force_stop (bool) -- Boolean value that indicates that the task may be

terminated by using TerminateProcess.

Parameters:	delete_after -- 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: :type: bool str - False (to disable) - Immediately - 30 days - 90 days - 180 days - 365 days

Parameters:	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, False if unsuccessful
Return type:	bool

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

Returns:
Return type:	dict

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

Returns:	Returns a list of actions.
Return type:	list

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

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

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

Returns:	Returns a list of triggers.
Return type:	list

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

Returns:	True if successful, False if unsuccessful
Return type:	bool

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

Returns:	True if successful, False if unsuccessful
Return type:	bool

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

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

• Unknown
• Disabled
• Queued
• Ready
• Running

Return type:	string

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

Returns:	True if successful, False if unsuccessful
Return type:	bool